@linxin666/dsh-pet 0.2.3 → 0.2.4

package/src/client/PetSprite.tsx

@@ -10,17 +10,18 @@
  */
 
 import { useEffect, useLayoutEffect, useRef, useState } from 'react'
-import type { CSSProperties, PointerEvent as ReactPointerEvent, ReactNode, ReactPortal } from 'react'
+import type { CSSProperties, PointerEvent as ReactPointerEvent, ReactElement, ReactNode, ReactPortal } from 'react'
 import { createPortal } from 'react-dom'
 import clsx from 'clsx'
 import type { TranslateNS } from '@deepseek-ai/dsh-client-ui-slots'
 import type { PetDisplayConfig } from '../persist.ts'
 import type { PetStateView } from '../service.ts'
 import type { PetDefinition } from '../registry.ts'
+import type { DecorationView } from '../contracts/status-decoration.ts'
 import type { PetFeedback } from './pet-store.ts'
 import { framePosition, rowOfTrack, trimTrack } from './spritesheet.ts'
 import { sequenceFrameAt } from './sequences.ts'
-import { animationForPhase, type PetAnimation } from '../state.ts'
+import { animationForPhase, type ActivityPhase, type PetAnimation } from '../state.ts'
 import { NS } from './locales.ts'
 import styles from './pet.module.css'
 
@@ -63,6 +64,81 @@ function clampOffset(value: number, max: number): number {
   return Math.max(0, Math.min(max, value))
 }
 
+/**
+ * The status decoration ornament (pet-center M5, #567). Renders the active
+ * phase's frame segment as a CSS-background strip at a compact bubble
+ * height; prefers-reduced-motion holds the segment's first frame, and a
+ * missing or undecodable asset simply paints nothing (CSS background
+ * failure) — the bubble text is never disturbed. The span is aria-hidden;
+ * the bubble keeps its own semantics untouched.
+ */
+function StatusOrnament(props: { decoration: DecorationView; phase: ActivityPhase }): ReactElement | null {
+  const { decoration, phase } = props
+  const segment = decoration.phases[phase]
+  const shown = segment !== undefined && segment !== 'hide'
+  const segmentKey = segment !== undefined && segment !== 'hide' ? segment.from + ':' + segment.to : 'none'
+  const spanRef = useRef<HTMLSpanElement | null>(null)
+  const scale = 18 / decoration.cell.height
+  const frameWidth = Math.round(decoration.cell.width * scale)
+  const stripWidth = decoration.columns * frameWidth
+  // Value-stable dependency key: the host serves a fresh DecorationView
+  // object on every state poll (2 s), so the effect must not depend on the
+  // object identity — otherwise each poll would cancel and restart the
+  // frame loop and the animation would jump back to its first frame.
+  const durationsKey = decoration.durations.join(',')
+  useEffect(() => {
+    if (segment === undefined || segment === 'hide') return
+    const el = spanRef.current
+    if (el === null) return
+    const position = (index: number): string => (-index * frameWidth) + 'px 0px'
+    const reduceMotion = window.matchMedia?.('(prefers-reduced-motion: reduce)')?.matches === true
+    el.style.backgroundPosition = position(segment.from)
+    if (reduceMotion) return
+    let raf = 0
+    let index = segment.from
+    let elapsed = 0
+    let last = performance.now()
+    const tick = (ts: number): void => {
+      const delta = ts - last
+      last = ts
+      elapsed += delta
+      const duration = decoration.durations[index] ?? 160
+      if (elapsed >= duration) {
+        elapsed = 0
+        if (index < segment.to) index += 1
+        else if (decoration.loop) index = segment.from
+      }
+      el.style.backgroundPosition = position(index)
+      // A non-looping segment settles on its last frame; stop scheduling
+      // instead of repainting the same position every frame.
+      if (!decoration.loop && index === segment.to) return
+      raf = requestAnimationFrame(tick)
+    }
+    raf = requestAnimationFrame(tick)
+    return () => cancelAnimationFrame(raf)
+  }, [shown, segmentKey, frameWidth, decoration.loop, durationsKey])
+  if (!shown) return null
+  return (
+    <span
+      ref={spanRef}
+      aria-hidden="true"
+      data-dsh-pet-decoration={decoration.id}
+      style={{
+        display: 'inline-block',
+        width: frameWidth,
+        height: 18,
+        marginRight: 6,
+        verticalAlign: 'middle',
+        flexShrink: 0,
+        backgroundImage: 'url(' + decoration.entryUrl + ')',
+        backgroundSize: stripWidth + 'px 18px',
+        backgroundRepeat: 'no-repeat',
+        backgroundPosition: '0px 0px',
+      }}
+    />
+  )
+}
+
 /**
  * The floating pet. The spritesheet frame advances on requestAnimationFrame
  * with per-frame durations from the definition's tracks; the atlas image is
@@ -110,6 +186,33 @@ export function PetSprite(props: PetSpriteProps): ReactPortal {
   const rows = definition.rows
   const tracks = definition.tracks
   const sequences = definition.sequences
+  // Hover-panel chrome from the pet's voice pack (pet-center M4, issue
+  // #677): every slot falls back to the i18n dictionary when unset. Stat
+  // formats carry {rank}/{n}/{points} placeholders the host validated.
+  const panel = definition.panel
+  const panelLabel = (slot: 'feed' | 'rename' | 'hide' | 'confirm', i18n: string): string =>
+    panel?.labels?.[slot] ?? i18n
+  const panelStat = (
+    slot: 'rank' | 'treats' | 'points',
+    i18nKey: 'pet.rank' | 'pet.treats' | 'pet.points',
+    values: Record<string, string | number>,
+  ): string => {
+    const format = panel?.stats?.[slot] ?? props.t(i18nKey, values)
+    if (panel?.stats?.[slot] === undefined) return format
+    // The host whitelists {rank}/{n}/{points} in every stat slot, so a pack
+    // format may reference any of them; substitute all three live values
+    // (the slot's own value plus the siblings) instead of only the slot's.
+    const all: Record<string, string | number> = {
+      rank: snapshot?.affinity.rank ?? '?',
+      n: snapshot?.treats.stocked ?? 0,
+      points: snapshot?.affinity.points ?? 0,
+    }
+    let text = format
+    for (const [name, value] of Object.entries(all)) text = text.replaceAll('{' + name + '}', String(value))
+    return text
+  }
+  const panelShows = (action: 'feed' | 'rename' | 'hide'): boolean =>
+    panel?.actions === undefined || panel.actions.includes(action)
 
   // Load the atlas once; the definition carries the authoritative per-row
   // frame counts and per-track durations, so nothing else is fetched. A
@@ -287,6 +390,8 @@ export function PetSprite(props: PetSpriteProps): ReactPortal {
   const whisper = feedback === null ? snapshot?.whisper : undefined
   const bubblePresent = feedback !== null || sessionBubbles.length > 0 || statusBubble !== undefined || whisper !== undefined
   const displayName = snapshot?.name ?? definition.displayName
+  // The host-served status decoration (M5, #567); absent = text-only bubbles.
+  const decoration = snapshot?.decoration
 
   // A settled session list can no longer stay pinned open.
   useEffect(() => {
@@ -408,6 +513,9 @@ export function PetSprite(props: PetSpriteProps): ReactPortal {
                 title={props.t('pet.openSessionHint')}
                 onClick={() => { props.onOpenSession(session.sessionId) }}
               >
+                {index === 0 && !speaksWhisper && decoration !== undefined && (
+                  <StatusOrnament decoration={decoration} phase={phase} />
+                )}
                 {speaksWhisper ? whisper : session.bubble}
               </button>
             )
@@ -446,6 +554,9 @@ export function PetSprite(props: PetSpriteProps): ReactPortal {
               role="status"
               aria-live="polite"
             >
+              {whisper === undefined && decoration !== undefined && (
+                <StatusOrnament decoration={decoration} phase={phase} />
+              )}
               {whisper ?? statusBubble}
             </div>
           )}
@@ -507,39 +618,45 @@ export function PetSprite(props: PetSpriteProps): ReactPortal {
                   }
                 }}
               >
-                {props.t('pet.confirm')}
+                {panelLabel('confirm', props.t('pet.confirm'))}
               </button>
             </div>
           ) : (
             <>
               <div className={styles.rankRow}>
                 <span className={styles.nameCell}>{displayName}</span>
-                <span className={styles.statRank}>{props.t('pet.rank', { rank: snapshot?.affinity.rank ?? '?' })}</span>
+                <span className={styles.statRank}>{panelStat('rank', 'pet.rank', { rank: snapshot?.affinity.rank ?? '?' })}</span>
               </div>
               <div className={styles.rankRow}>
-                <span className={styles.statTreats}>{props.t('pet.treats', { n: snapshot?.treats.stocked ?? 0 })}</span>
-                <span className={styles.statPoints}>{props.t('pet.points', { points: snapshot?.affinity.points ?? 0 })}</span>
+                <span className={styles.statTreats}>{panelStat('treats', 'pet.treats', { n: snapshot?.treats.stocked ?? 0 })}</span>
+                <span className={styles.statPoints}>{panelStat('points', 'pet.points', { points: snapshot?.affinity.points ?? 0 })}</span>
               </div>
               <div className={styles.actions}>
-                <button type="button" className={styles.action} onClick={props.onFeed}>
-                  {props.t('pet.feed')}
-                </button>
-                <button
-                  type="button"
-                  className={styles.action}
-                  onClick={() => {
-                    // Cancel any pending hide so the rename box cannot
-                    // unmount right as the user starts typing (#303).
-                    clearHideTimer()
-                    setNameDraft(displayName)
-                    setRenaming(true)
-                  }}
-                >
-                  {props.t('pet.rename')}
-                </button>
-                <button type="button" className={styles.action} onClick={props.onHide}>
-                  {props.t('pet.hide')}
-                </button>
+                {panelShows('feed') && (
+                  <button type="button" className={styles.action} onClick={props.onFeed}>
+                    {panelLabel('feed', props.t('pet.feed'))}
+                  </button>
+                )}
+                {panelShows('rename') && (
+                  <button
+                    type="button"
+                    className={styles.action}
+                    onClick={() => {
+                      // Cancel any pending hide so the rename box cannot
+                      // unmount right as the user starts typing (#303).
+                      clearHideTimer()
+                      setNameDraft(displayName)
+                      setRenaming(true)
+                    }}
+                  >
+                    {panelLabel('rename', props.t('pet.rename'))}
+                  </button>
+                )}
+                {panelShows('hide') && (
+                  <button type="button" className={styles.action} onClick={props.onHide}>
+                    {panelLabel('hide', props.t('pet.hide'))}
+                  </button>
+                )}
               </div>
             </>
           )}

package/src/client/locales.ts

@@ -34,6 +34,8 @@ export const zh = {
   'settings.petHint': '选择显示哪只宠物；每只宠物独立命名，可在宠物悬浮面板改名。',
   'settings.enabled': '启用宠物',
   'settings.enabledHint': '关闭后隐藏宠物并停止轮询，可在设置里重新启用。',
+  'settings.decoration': '状态装饰',
+  'settings.decorationHint': '在宠物状态气泡里显示喷水鲸鱼等状态装饰；关闭后气泡只剩文字。',
   'settings.visible': '显示宠物',
   'settings.visibleHint': '关闭后宠物隐藏，可从聊天输入区重新召唤。',
   'settings.size': '大小（px）',
@@ -87,6 +89,8 @@ export const en = {
   '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.decoration': 'Status decoration',
+  'settings.decorationHint': 'Show ornaments like the spouting whale inside the pet status bubbles; when off, bubbles stay text-only.',
   'settings.visible': 'Show the pet',
   'settings.visibleHint': 'When off, the pet hides; summon it again from the input row.',
   'settings.size': 'Size (px)',

package/src/client/renderers/live2d.test.ts

@@ -75,13 +75,17 @@ function fakeApp(): FakeApp {
   return app
 }
 
-function fakeVendor(model: FakeModel, app: FakeApp): unknown {
+function fakeVendor(
+  model: FakeModel,
+  app: FakeApp,
+  from: (source: string, options?: Record<string, unknown>) => Promise<FakeModel> = () => Promise.resolve(model),
+): unknown {
   return {
     Application: class { constructor() { return app } },
     extensions: { add: () => {} },
     Live2DPlugin: {},
     configureCubismSDK: () => {},
-    Live2DModel: { from: () => Promise.resolve(model) },
+    Live2DModel: { from },
   }
 }
 
@@ -142,6 +146,23 @@ describe('live2dRenderer', () => {
     expect(app.destroyed).toBe(1)
   })
 
+  it('uses one automatic texture LOD instead of the default full mip chain', async () => {
+    const model = fakeModel()
+    const app = fakeApp()
+    const from = vi.fn(async () => model)
+    runtime.vendor = fakeVendor(model, app, from)
+    const { ctx } = makeCtx()
+
+    live2dRenderer.mount(ctx, live2dRenderer.validateConfig(CONFIG))
+    await flush()
+
+    expect(from).toHaveBeenCalledWith(CONFIG.modelUrl, {
+      autoHitTest: false,
+      autoFocus: false,
+      textureOptions: { lod: 'single-auto' },
+    })
+  })
+
   it('falls back to the idle group when a mapped group is absent from the model', async () => {
     const model = fakeModel({ Idle: [{}] })
     runtime.vendor = fakeVendor(model, fakeApp())

package/src/client/renderers/live2d.ts

@@ -60,6 +60,15 @@ export interface Live2dRendererHandle extends PetRendererHandle {
 /** The de-facto tap-motion group of Cubism sample models. */
 const TAP_GROUP = 'TapBody'
 
+/**
+ * Keep one screen-appropriate atlas LOD instead of asking Pixi for the
+ * engine's default full mip chain. A user model can legitimately carry an
+ * 8192px texture while the pet itself is only a few hundred pixels tall;
+ * `single-auto` preserves the source for larger renders and generates one
+ * downsampled atlas only when the effective on-screen scale warrants it.
+ */
+const TEXTURE_OPTIONS = { lod: 'single-auto' } as const
+
 let vendorConfigured = false
 
 /** Configure pixi extensions + the Cubism SDK once per page. */
@@ -150,7 +159,11 @@ export const live2dRenderer: PetRenderer<PetLive2dConfig> = {
       pixiApp.canvas.style.width = '100%'
       pixiApp.canvas.style.height = '100%'
       ctx.container.appendChild(pixiApp.canvas)
-      const loaded = await vendor.Live2DModel.from(config.modelUrl, { autoHitTest: false, autoFocus: false })
+      const loaded = await vendor.Live2DModel.from(config.modelUrl, {
+        autoHitTest: false,
+        autoFocus: false,
+        textureOptions: TEXTURE_OPTIONS,
+      })
       if (disposed) {
         pixiApp.destroy(true, { children: true })
         return

package/src/client/settings-form.ts

@@ -333,9 +333,11 @@ export class CardForm<T> {
     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))
+    // Snapshot the staged entries this save writes, so an edit staged while it
+    // is in flight (which replaces the same key) survives: only delete the key
+    // when the entry is still the one this save started from.
+    const pending = new Map<string, StagedEdit | undefined>()
+    for (const item of plan) pending.set(item.field, this.staged.get(item.field))
     this.saving = true
     this.failed = false
     this.failedReason = undefined
@@ -356,11 +358,11 @@ export class CardForm<T> {
         if (await item.run!()) landed.add(item.field)
       }
     }
-    for (const field of fields) {
-      if (landed.has(field)) this.staged.delete(field)
+    for (const [field, before] of pending) {
+      if (landed.has(field) && this.staged.get(field) === before) this.staged.delete(field)
     }
     this.saving = false
-    this.failed = landed.size !== fields.size
+    this.failed = landed.size !== pending.size
     this.publish()
   }
 

package/src/contracts/status-decoration.ts

@@ -0,0 +1,78 @@
+/**
+ * Status-decoration contract — the L3 extension slot for small status
+ * ornaments (issue #623 milestone M5, protocol #567, first reference
+ * implementation #463). A decoration is an INDEPENDENT content entry (own
+ * id, own directory, own descriptor) whose PNG/WebP sprite strip ornaments
+ * the pet center's status bubble chrome; it never touches the pet
+ * manifests and never changes the bubble's semantics.
+ *
+ * Adopted disciplines (#623): entry assets are PNG/WebP sprite strips only
+ * (no SVG, no CSS animation); the bubble's own role=status/aria-live (or
+ * session-bubble button semantics) always stays intact and the ornament is
+ * aria-hidden; load failure or prefers-reduced-motion degrades to no
+ * ornament or the static first frame.
+ *
+ * The ActivityPhase stream the pet center owns drives the ornament: each
+ * phase binds to a frame segment (inclusive from/to indices into the
+ * strip) or to 'hide' (no ornament for that phase; the default).
+ * @module @linxin666/dsh-pet/contracts/status-decoration
+ */
+
+import type { ActivityPhase } from '../state.ts'
+
+/** Contract version decorations declare against (independent of manifests). */
+export const PET_DECORATION_API_VERSION = 'x-org.linxin666.pet-center/status-decoration-v1' as const
+
+/** One phase binding: a frame segment, or hidden. */
+export type PhaseSegment = { from: number; to: number } | 'hide'
+
+/** The ActivityPhase -> frame-segment binding table (unmapped phases hide). */
+export type PhaseBindings = Partial<Record<ActivityPhase, PhaseSegment>>
+
+/** Normalized decoration descriptor as the registry consumes it. */
+export interface DecorationManifest {
+  decorationManifestVersion: 1
+  id: string
+  displayName: string
+  license: string
+  /** Strip path relative to the descriptor directory (PNG/WebP). */
+  entry: string
+  cell: { width: number; height: number }
+  columns: number
+  /** Per-frame duration ms (same length as columns, or a single constant). */
+  durations: number[]
+  loop: boolean
+  phases: PhaseBindings
+}
+
+/** One structured diagnostic emitted while parsing a descriptor. */
+export interface DecorationDiagnostic {
+  level: 'error' | 'warning'
+  message: string
+}
+
+/** Parse outcome: a usable descriptor plus diagnostics, or rejection. */
+export type DecorationManifestParse =
+  | { ok: true; manifest: DecorationManifest; diagnostics: DecorationDiagnostic[] }
+  | { ok: false; diagnostics: DecorationDiagnostic[] }
+
+/**
+ * The decoration block the host serves inside the pet state view — exactly
+ * what the browser half needs to render the ornament, nothing more. The
+ * apiVersion rides the wire so a future protocol revision can be detected
+ * and negotiated by clients (review-spd follow-up, pet-center M5).
+ */
+export interface DecorationView {
+  /** The protocol version this view speaks (PET_DECORATION_API_VERSION). */
+  apiVersion: typeof PET_DECORATION_API_VERSION
+  id: string
+  /** Same-origin URL prefix of the decoration's assets. */
+  assetBase: string
+  /** Browser URL of the strip. */
+  entryUrl: string
+  cell: { width: number; height: number }
+  columns: number
+  durations: number[]
+  loop: boolean
+  phases: PhaseBindings
+}

package/src/decoration.test.ts

@@ -0,0 +1,178 @@
+/**
+ * Status-decoration manifest tests (pet-center M5, #567): fail-closed
+ * structure, warn-and-drop content, duration normalization and the
+ * PNG/WebP entry discipline.
+ */
+import { describe, expect, it } from 'vitest'
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { KNOWN_DECORATION_TOP_LEVEL, parseDecorationManifest, safeDecorationEntry } from './decoration.ts'
+import { PET_ACTIVITY_PHASES } from './manifest-v2.ts'
+import { petPackageRoot } from './registry.ts'
+
+function parse(raw: unknown) {
+  return parseDecorationManifest(raw, 'test/decoration.json')
+}
+
+function valid(): Record<string, unknown> {
+  return {
+    decorationManifestVersion: 1,
+    id: 'whale',
+    displayName: '喷水鲸鱼',
+    license: 'MIT',
+    entry: 'whale-frames.png',
+    cell: { width: 64, height: 48 },
+    columns: 4,
+    frameMs: 140,
+    loop: true,
+    phases: {
+      idle: 'hide',
+      waiting: { from: 0, to: 1 },
+      thinking: { from: 0, to: 3 },
+    },
+  }
+}
+
+describe('parseDecorationManifest structure', () => {
+  it('accepts a valid descriptor with duration and display-name defaults', () => {
+    const verdict = parse(valid())
+    expect(verdict.ok).toBe(true)
+    if (!verdict.ok) return
+    expect(verdict.manifest.durations).toEqual([140, 140, 140, 140])
+    expect(verdict.manifest.loop).toBe(true)
+    expect(verdict.manifest.phases.thinking).toEqual({ from: 0, to: 3 })
+    expect(verdict.manifest.phases.idle).toBe('hide')
+  })
+
+  it('defaults displayName to the id and frameMs to 120', () => {
+    const manifest = { ...valid() }
+    delete manifest.displayName
+    delete manifest.frameMs
+    const verdict = parse(manifest)
+    expect(verdict.ok).toBe(true)
+    if (!verdict.ok) return
+    expect(verdict.manifest.displayName).toBe('whale')
+    expect(verdict.manifest.durations).toEqual([120, 120, 120, 120])
+  })
+
+  it('rejects non-object roots, wrong versions and unknown top-level fields', () => {
+    expect(parse(['x']).ok).toBe(false)
+    const wrongVersion = { ...valid(), decorationManifestVersion: 2 }
+    const verdict = parse(wrongVersion)
+    expect(verdict.ok).toBe(false)
+    if (verdict.ok) return
+    expect(verdict.diagnostics.some(d => d.message.includes('decorationManifestVersion'))).toBe(true)
+    const unknown = { ...valid(), mystery: true }
+    expect(parse(unknown).ok).toBe(false)
+  })
+
+  it('rejects unsafe or non-image entries', () => {
+    for (const entry of ['../etc/passwd', '/abs.png', 'a.svg', 'a.css', 'x\\y.png']) {
+      const verdict = parse({ ...valid(), entry })
+      expect(verdict.ok).toBe(false)
+    }
+  })
+
+  it('rejects out-of-range geometry and missing license/id', () => {
+    expect(parse({ ...valid(), cell: { width: 999, height: 48 } }).ok).toBe(false)
+    expect(parse({ ...valid(), columns: 99 }).ok).toBe(false)
+    expect(parse({ ...valid(), license: '' }).ok).toBe(false)
+    expect(parse({ ...valid(), id: 'Bad Id' }).ok).toBe(false)
+  })
+})
+
+describe('parseDecorationManifest content (warn-and-drop)', () => {
+  it('drops unknown phase keys and out-of-range segments with warnings', () => {
+    const verdict = parse({
+      ...valid(),
+      phases: {
+        ...(valid().phases as Record<string, unknown>),
+        bogus: { from: 0, to: 1 },
+        waiting: { from: 2, to: 9 },
+        review: { from: 3, to: 1 },
+      },
+    })
+    expect(verdict.ok).toBe(true)
+    if (!verdict.ok) return
+    expect(verdict.manifest.phases.done).toBeUndefined()
+    expect(verdict.manifest.phases.waiting).toBeUndefined()
+    expect(verdict.manifest.phases.review).toBeUndefined()
+    expect(verdict.diagnostics.some(d => d.level === 'warning' && d.message.includes('ignored'))).toBe(true)
+  })
+
+  it('warns when no phase shows the ornament', () => {
+    const verdict = parse({ ...valid(), phases: { idle: 'hide' } })
+    expect(verdict.ok).toBe(true)
+    expect(verdict.diagnostics.some(d => d.level === 'warning' && d.message.includes('stays hidden'))).toBe(true)
+  })
+
+  it('falls back to the constant frameMs when durations has the wrong length', () => {
+    const verdict = parse({ ...valid(), durations: [100] })
+    expect(verdict.ok).toBe(true)
+    if (!verdict.ok) return
+    expect(verdict.manifest.durations).toEqual([140, 140, 140, 140])
+    expect(verdict.diagnostics.some(d => d.level === 'warning' && d.message.includes('durations'))).toBe(true)
+  })
+
+  it('keeps a well-sized durations array', () => {
+    const verdict = parse({ ...valid(), durations: [120, 130, 140, 150] })
+    expect(verdict.ok).toBe(true)
+    if (!verdict.ok) return
+    expect(verdict.manifest.durations).toEqual([120, 130, 140, 150])
+  })
+
+  it('warns and defaults to looping when loop is not a boolean', () => {
+    const verdict = parse({ ...valid(), loop: 'yes' })
+    expect(verdict.ok).toBe(true)
+    if (!verdict.ok) return
+    expect(verdict.manifest.loop).toBe(true)
+    expect(verdict.diagnostics.some(d => d.level === 'warning' && d.message.includes('loop'))).toBe(true)
+    const off = parse({ ...valid(), loop: false })
+    expect(off.ok && off.manifest.loop).toBe(false)
+  })
+})
+
+describe('safeDecorationEntry', () => {
+  it('accepts safe relative PNG/WebP paths and rejects everything else', () => {
+    expect(safeDecorationEntry('frames.webp')).toBe('frames.webp')
+    expect(safeDecorationEntry('a/b.png')).toBe('a/b.png')
+    expect(safeDecorationEntry('')).toBeUndefined()
+    expect(safeDecorationEntry('a/../b.png')).toBeUndefined()
+    expect(safeDecorationEntry('/tmp/x.png')).toBeUndefined()
+    expect(safeDecorationEntry('x.svg')).toBeUndefined()
+    expect(safeDecorationEntry('x')).toBeUndefined()
+  })
+
+  it('rejects case-mismatched extensions (the route serves paths verbatim)', () => {
+    // A lenient case check would pass validation here, but the asset route
+    // matches the declared path exactly and 403s on case-sensitive hosts.
+    expect(safeDecorationEntry('img/FRAMES.PNG')).toBeUndefined()
+    expect(safeDecorationEntry('img/frames.WebP')).toBeUndefined()
+    expect(safeDecorationEntry('img/frames.png')).toBe('img/frames.png')
+  })
+})
+
+describe('status-decoration schema file drift lock', () => {
+  const schema = JSON.parse(readFileSync(
+    join(petPackageRoot(import.meta.url), 'contracts', 'status-decoration-v1.schema.json'),
+    'utf8',
+  )) as {
+    required: string[]
+    properties: Record<string, { const?: number; properties?: Record<string, unknown> }>
+  }
+
+  it('locks the schema top-level fields to the validator allow-list', () => {
+    expect(new Set(Object.keys(schema.properties))).toEqual(KNOWN_DECORATION_TOP_LEVEL)
+  })
+
+  it('locks the required set and the version const', () => {
+    expect([...schema.required].sort()).toEqual([
+      'cell', 'columns', 'decorationManifestVersion', 'entry', 'id', 'license',
+    ])
+    expect(schema.properties.decorationManifestVersion?.const).toBe(1)
+  })
+
+  it('locks the phases key set to the ActivityPhase stream', () => {
+    expect(new Set(Object.keys(schema.properties.phases?.properties ?? {}))).toEqual(new Set(PET_ACTIVITY_PHASES))
+  })
+})