@linxin666/dsh-pet 0.2.2 → 0.2.4

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))
+  })
+})

package/src/decoration.ts

@@ -0,0 +1,220 @@
+/**
+ * Status-decoration manifest v1 — fail-closed structure + warn-and-drop
+ * content, mirroring the pet manifest-v2 discipline (issue #623 M5,
+ * protocol #567). Unknown top-level fields, unsafe entry paths, out-of-
+ * range geometry and unknown renderer content reject the descriptor with
+ * human-readable diagnostics; per-phase binding issues drop that binding
+ * only. The JSON Schema twin lives at
+ * contracts/status-decoration-v1.schema.json; this hand-rolled parser is
+ * authoritative. Keep this file erasable-syntax-only (scripts/ import it
+ * under node's strip-only mode).
+ * @module @linxin666/dsh-pet/decoration
+ */
+
+import { isAbsolute } from 'node:path'
+import type { ActivityPhase } from './state.ts'
+import { PET_ACTIVITY_PHASES } from './manifest-v2.ts'
+import type {
+  DecorationDiagnostic,
+  DecorationManifest,
+  DecorationManifestParse,
+  PhaseBindings,
+  PhaseSegment,
+} from './contracts/status-decoration.ts'
+
+/** Geometry and content caps (the adopted PNG/WebP sprite-strip bounds). */
+export const DECORATION_CELL_MAX = 256
+export const DECORATION_COLUMNS_MAX = 16
+export const DECORATION_DURATION_MAX_MS = 2000
+export const DECORATION_ENTRY_EXTENSIONS = ['.webp', '.png'] as const
+export const DECORATION_DISPLAY_NAME_MAX = 64
+
+/** Field allow-list (drift-locked to the schema twin in tests). */
+export const KNOWN_DECORATION_TOP_LEVEL = new Set([
+  '$schema', 'decorationManifestVersion', 'id', 'displayName', 'license',
+  'entry', 'cell', 'columns', 'frameMs', 'durations', 'loop', 'phases',
+])
+
+const PET_ID_PATTERN = /^[a-z0-9][a-z0-9-]*$/
+const PATH_SEGMENT_PATTERN = /^[A-Za-z0-9._-]+$/
+
+class Diagnostics {
+  readonly list: DecorationDiagnostic[] = []
+  private readonly source: string
+  constructor(source: string) { this.source = source }
+  error(message: string): void { this.list.push({ level: 'error', message: this.source + ': ' + message }) }
+  warn(message: string): void { this.list.push({ level: 'warning', message: this.source + ': ' + message }) }
+  get hasErrors(): boolean { return this.list.some(d => d.level === 'error') }
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+function unknownKeys(source: Record<string, unknown>, known: Set<string>): string[] {
+  return Object.keys(source).filter(key => !known.has(key))
+}
+
+/** Positive integer in [min, max], else undefined. */
+function finiteInt(value: unknown, min: number, max: number): number | undefined {
+  return typeof value === 'number' && Number.isInteger(value) && value >= min && value <= max
+    ? value
+    : undefined
+}
+
+/**
+ * Validate a descriptor-relative entry path: no absolute paths, no
+ * backslashes, no traversal, plain safe segments only, and an exact
+ * lowercase PNG/WebP extension (the adopted entry discipline — SVG/CSS are
+ * not accepted). The extension match is case-sensitive on purpose: the
+ * asset route serves the declared path verbatim, so a case-mismatched
+ * suffix (frames.PNG vs frames.png) would pass a lenient check but 403 on
+ * case-sensitive filesystems.
+ * Returns the normalized path or undefined.
+ */
+export function safeDecorationEntry(raw: unknown): string | undefined {
+  if (typeof raw !== 'string' || raw.trim() === '') return undefined
+  const value = raw.trim()
+  if (value.length > 256) return undefined
+  if (isAbsolute(value) || value.includes('\\') || /^[a-z][a-z0-9+.-]*:/i.test(value)) return undefined
+  const segments = value.split('/').filter(segment => segment !== '')
+  if (segments.length === 0) return undefined
+  if (segments.some(segment => segment === '.' || segment === '..' || !PATH_SEGMENT_PATTERN.test(segment))) return undefined
+  const last = segments[segments.length - 1]!
+  const dot = last.lastIndexOf('.')
+  if (dot <= 0 || !(DECORATION_ENTRY_EXTENSIONS as readonly string[]).includes(last.slice(dot))) return undefined
+  return segments.join('/')
+}
+
+/** Normalize one phase binding value; undefined (warning) on bad content. */
+function normalizeSegment(
+  raw: unknown,
+  columns: number,
+  diag: Diagnostics,
+): PhaseSegment | undefined {
+  if (raw === 'hide') return 'hide'
+  if (!isRecord(raw)) {
+    diag.warn('phase binding must be "hide" or { from, to }; binding dropped')
+    return undefined
+  }
+  const from = finiteInt(raw.from, 0, columns - 1)
+  const to = finiteInt(raw.to, 0, columns - 1)
+  if (from === undefined || to === undefined || from > to) {
+    diag.warn('phase frame segment out of range; binding dropped')
+    return undefined
+  }
+  return { from, to }
+}
+
+/**
+ * Parse and validate one decoration.json document. Fail-closed over the
+ * structure (types, key sets, paths, ranges); phase-binding content issues
+ * drop that binding only (warn-and-drop, the registry never-throw rule).
+ */
+export function parseDecorationManifest(
+  raw: unknown,
+  source: string = 'decoration.json',
+): DecorationManifestParse {
+  const diag = new Diagnostics(source)
+  if (!isRecord(raw)) {
+    diag.error('descriptor must be a JSON object')
+    return { ok: false, diagnostics: diag.list }
+  }
+  for (const key of unknownKeys(raw, KNOWN_DECORATION_TOP_LEVEL)) {
+    diag.error('unknown top-level field ' + JSON.stringify(key))
+  }
+  if (raw.decorationManifestVersion !== 1) {
+    diag.error('decorationManifestVersion must be 1')
+  }
+  const id = typeof raw.id === 'string' ? raw.id.trim() : ''
+  if (!PET_ID_PATTERN.test(id)) {
+    diag.error('id must be a lowercase kebab id')
+  }
+  if (id.length > 64) {
+    diag.error('id must be at most 64 characters')
+  }
+  const license = typeof raw.license === 'string' ? raw.license.trim() : ''
+  if (license === '') diag.error('license is required (asset provenance)')
+  if (license.length > 128) {
+    diag.error('license must be at most 128 characters')
+  }
+  const entry = safeDecorationEntry(raw.entry)
+  if (entry === undefined) {
+    diag.error('entry must be a safe relative PNG/WebP path')
+  }
+  const rawCell = isRecord(raw.cell) ? raw.cell : {}
+  for (const key of Object.keys(rawCell)) {
+    if (key !== 'width' && key !== 'height') diag.warn('unknown cell field ' + JSON.stringify(key) + ' ignored')
+  }
+  const cellWidth = finiteInt(rawCell.width, 1, DECORATION_CELL_MAX)
+  const cellHeight = finiteInt(rawCell.height, 1, DECORATION_CELL_MAX)
+  if (cellWidth === undefined || cellHeight === undefined) {
+    diag.error('cell width/height must be integers in [1, ' + DECORATION_CELL_MAX + ']')
+  }
+  const columns = finiteInt(raw.columns, 1, DECORATION_COLUMNS_MAX)
+  if (columns === undefined) {
+    diag.error('columns must be an integer in [1, ' + DECORATION_COLUMNS_MAX + ']')
+  }
+  if (diag.hasErrors || id === '' || entry === undefined || columns === undefined) {
+    return { ok: false, diagnostics: diag.list }
+  }
+  const displayName = typeof raw.displayName === 'string' && raw.displayName.trim() !== ''
+    ? raw.displayName.trim().slice(0, DECORATION_DISPLAY_NAME_MAX)
+    : id
+  let loop: boolean
+  if (raw.loop === undefined || typeof raw.loop === 'boolean') {
+    loop = raw.loop ?? true
+  } else {
+    diag.warn('loop must be a boolean; defaulting to true')
+    loop = true
+  }
+  const rawDurations = raw.durations
+  let durations: number[]
+  if (Array.isArray(rawDurations)) {
+    const usable = rawDurations.filter((v): v is number => typeof v === 'number' && Number.isInteger(v) && v >= 1 && v <= DECORATION_DURATION_MAX_MS)
+    if (usable.length !== columns) {
+      diag.warn('durations length must equal columns; using the constant frameMs instead')
+      durations = []
+    } else {
+      durations = usable
+    }
+  } else if (rawDurations !== undefined) {
+    diag.warn('durations must be an array; using the constant frameMs instead')
+    durations = []
+  } else {
+    durations = []
+  }
+  if (durations.length === 0) {
+    const frameMs = finiteInt(raw.frameMs, 1, DECORATION_DURATION_MAX_MS) ?? 120
+    durations = Array.from({ length: columns }, () => frameMs)
+  }
+  const phases: PhaseBindings = {}
+  const rawPhases = raw.phases
+  if (isRecord(rawPhases)) {
+    for (const [key, value] of Object.entries(rawPhases)) {
+      if (!(PET_ACTIVITY_PHASES as readonly string[]).includes(key)) {
+        diag.warn('unknown phase ' + JSON.stringify(key) + '; binding ignored')
+        continue
+      }
+      const segment = normalizeSegment(value, columns, diag)
+      if (segment !== undefined) phases[key as ActivityPhase] = segment
+    }
+  } else if (rawPhases !== undefined) {
+    diag.warn('phases must be an object; all phases hide')
+  }
+  const visible = Object.values(phases).some(segment => segment !== 'hide')
+  if (!visible) diag.warn('no phase shows the ornament; the decoration stays hidden')
+  const manifest: DecorationManifest = {
+    decorationManifestVersion: 1,
+    id,
+    displayName,
+    license,
+    entry,
+    cell: { width: cellWidth!, height: cellHeight! },
+    columns,
+    durations,
+    loop,
+    phases,
+  }
+  return { ok: true, manifest, diagnostics: diag.list }
+}

package/src/event-projection.ts

@@ -13,7 +13,7 @@
 
 import type { SessionEvent } from '@deepseek-ai/dsh-session'
 import type { PetStateInput } from './state.ts'
-import { StatusVoice, toolArgHint, WhisperEngine } from './chatter.ts'
+import { StatusVoice, toolArgHint, WhisperEngine, type VoicePoolsProvider } from './chatter.ts'
 
 /** Runtime shape of the optional legacy activity event. */
 export interface ActivityStatusEventLike {
@@ -41,14 +41,19 @@ export interface PetActivityTransition {
   whisper?: string
 }
 
-/** Fresh projection runtime for a newly seen session. */
-export function emptyProjectionRuntime(): ProjectionRuntime {
+/**
+ * Fresh projection runtime for a newly seen session. The optional voice-pack
+ * provider (pet-center M4, issue #677) hands both chatter engines their
+ * pools; engines resolve overrides at draw time, so swapping the provider's
+ * pack re-voices live runtimes without rebuilding them.
+ */
+export function emptyProjectionRuntime(pools?: VoicePoolsProvider): ProjectionRuntime {
   return {
     activeTools: new Set(),
     officialEventsSeen: false,
     stepHadFailure: false,
-    voice: new StatusVoice(),
-    whispers: new WhisperEngine(),
+    voice: new StatusVoice(pools),
+    whispers: new WhisperEngine(pools),
   }
 }
 

package/src/index.ts

@@ -134,6 +134,7 @@ export function makePetSettingsSchema(fallbackPetId: string) {
     bottom: z.number().step(1).min(0).max(DISPLAY_INSET_MAX).default(20),
     petId: z.string().default(fallbackPetId),
     enabled: z.boolean().default(true),
+    decorationEnabled: z.boolean().default(true),
   })
 }
 
@@ -163,6 +164,7 @@ function applyImpl(ctx: Context, config: PetConfig = {}): void {
     bottom: service.display().bottom,
     petId: service.selectedPetId(),
     enabled: config.enabled ?? true,
+    decorationEnabled: config.decorationEnabled ?? true,
   }
   // The browser half talks to the pet through same-origin JSON endpoints and
   // loads each pet's atlas from the registry's own media route (RPC domains