@linxin666/dsh-pet 0.2.3 → 0.2.5

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/image-dimensions.test.ts

@@ -0,0 +1,85 @@
+import { describe, expect, it } from 'vitest'
+import { imageDimensions } from './image-dimensions.ts'
+
+/** Minimal PNG header (signature + IHDR) for the given size. */
+function pngHeader(width: number, height: number): Buffer {
+  const buf = Buffer.alloc(26)
+  Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]).copy(buf, 0)
+  buf.writeUInt32BE(13, 8)
+  buf.write('IHDR', 12)
+  buf.writeUInt32BE(width, 16)
+  buf.writeUInt32BE(height, 20)
+  return buf
+}
+
+/** Minimal extended WebP header (RIFF + VP8X) for the given size. */
+function webpExtendedHeader(width: number, height: number): Buffer {
+  const buf = Buffer.alloc(30)
+  buf.write('RIFF', 0)
+  buf.writeUInt32LE(30 - 8, 4)
+  buf.write('WEBP', 8)
+  buf.write('VP8X', 12)
+  buf[20] = 0 // flags: none
+  buf.writeUIntLE(width - 1, 24, 3)
+  buf.writeUIntLE(height - 1, 27, 3)
+  return buf
+}
+
+/** Minimal lossless WebP header (RIFF + VP8L). */
+function webpLosslessHeader(width: number, height: number): Buffer {
+  const buf = Buffer.alloc(25)
+  buf.write('RIFF', 0)
+  buf.writeUInt32LE(25 - 8, 4)
+  buf.write('WEBP', 8)
+  buf.write('VP8L', 12)
+  buf[20] = 0x2f
+  const bits = (width - 1) | ((height - 1) << 14)
+  buf.writeUInt32LE(bits, 21)
+  return buf
+}
+
+/** Minimal lossy WebP header (RIFF + VP8 ) — low 14 bits carry the size. */
+function webpLossyHeader(width: number, height: number): Buffer {
+  const buf = Buffer.alloc(30)
+  buf.write('RIFF', 0)
+  buf.writeUInt32LE(30 - 8, 4)
+  buf.write('WEBP', 8)
+  buf.write('VP8 ', 12)
+  buf.writeUInt16LE(width & 0x3fff, 26)
+  buf.writeUInt16LE(height & 0x3fff, 28)
+  return buf
+}
+
+describe('imageDimensions (decoration strip geometry)', () => {
+  it('reads a PNG header', () => {
+    expect(imageDimensions(pngHeader(256, 48))).toEqual({ width: 256, height: 48 })
+    expect(imageDimensions(pngHeader(64, 48))).toEqual({ width: 64, height: 48 })
+  })
+
+  it('reads an extended WebP header (VP8X)', () => {
+    expect(imageDimensions(webpExtendedHeader(128, 64))).toEqual({ width: 128, height: 64 })
+  })
+
+  it('reads a lossless WebP header (VP8L)', () => {
+    expect(imageDimensions(webpLosslessHeader(300, 200))).toEqual({ width: 300, height: 200 })
+  })
+
+  it('reads a lossy WebP header (VP8 )', () => {
+    expect(imageDimensions(webpLossyHeader(80, 40))).toEqual({ width: 80, height: 40 })
+  })
+
+  it('returns undefined for non-image bytes and truncated headers', () => {
+    expect(imageDimensions(Buffer.from('not-an-image'))).toBeUndefined()
+    expect(imageDimensions(Buffer.alloc(0))).toBeUndefined()
+    expect(imageDimensions(Buffer.from([0x89, 0x50]))).toBeUndefined()
+    // PNG magic but truncated before IHDR width/height.
+    expect(imageDimensions(pngHeader(10, 10).subarray(0, 10))).toBeUndefined()
+  })
+
+  it('returns undefined for a RIFF buffer that is not WebP', () => {
+    const riff = Buffer.alloc(16)
+    riff.write('RIFF', 0)
+    riff.write('AVI ', 8)
+    expect(imageDimensions(riff)).toBeUndefined()
+  })
+})

package/src/image-dimensions.ts

@@ -0,0 +1,76 @@
+/**
+ * Minimal PNG/WebP dimension reader — header-only, no decoding, no
+ * dependencies. Used by the decoration registry to verify a strip's actual
+ * pixel geometry matches its descriptor (single-row sprite strip; the client
+ * renders by frame-column offsets, so a mismatched strip silently shows the
+ * wrong frames). Parsing is best-effort: an unrecognized or truncated header
+ * returns undefined (the caller decides whether to warn).
+ *
+ * PNG: signature (8) + IHDR chunk — length (4) + 'IHDR' (4) + width (4) +
+ * height (4), both big-endian uint32 at fixed offsets 16/20.
+ * WebP: RIFF header (12) + chunk — 'VP8X' extended (width-1/height-1 as
+ * little-endian uint24 at 24/27), 'VP8L' lossless (packed 14-bit dims at
+ * 21), or 'VP8 ' lossy (frame header, low 14 bits of the uint16 at 26/28).
+ * @module @linxin666/dsh-pet/image-dimensions
+ */
+
+const PNG_SIGNATURE = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a])
+
+export interface ImageDimensions {
+  width: number
+  height: number
+}
+
+/** Read the pixel size of a PNG buffer, or undefined when unrecognized. */
+function pngDimensions(buf: Buffer): ImageDimensions | undefined {
+  if (buf.length < 24) return undefined
+  if (!buf.subarray(0, 8).equals(PNG_SIGNATURE)) return undefined
+  if (buf.toString('ascii', 12, 16) !== 'IHDR') return undefined
+  return { width: buf.readUInt32BE(16), height: buf.readUInt32BE(20) }
+}
+
+/** Read the pixel size of a WebP buffer, or undefined when unrecognized. */
+function webpDimensions(buf: Buffer): ImageDimensions | undefined {
+  if (buf.length < 21) return undefined
+  if (buf.toString('ascii', 0, 4) !== 'RIFF') return undefined
+  if (buf.toString('ascii', 8, 12) !== 'WEBP') return undefined
+  const fourcc = buf.toString('ascii', 12, 16)
+  if (fourcc === 'VP8X') {
+    // Extended header: 1-byte flags at 20, then width-1/height-1 uint24 LE.
+    if (buf.length < 30) return undefined
+    return {
+      width: 1 + buf.readUIntLE(24, 3),
+      height: 1 + buf.readUIntLE(27, 3),
+    }
+  }
+  if (fourcc === 'VP8L') {
+    // Lossless header: 0x2f marker at 20, then 14-bit width / 14-bit height
+    // packed into the little-endian uint32 at 21.
+    if (buf.length < 25) return undefined
+    const bits = buf.readUInt32LE(21)
+    return {
+      width: 1 + (bits & 0x3fff),
+      height: 1 + ((bits >>> 14) & 0x3fff),
+    }
+  }
+  if (fourcc === 'VP8 ') {
+    // Lossy frame header: 3-byte tag + 3-byte start code, then width/height
+    // as uint16 LE whose low 14 bits carry the dimension.
+    if (buf.length < 30) return undefined
+    return {
+      width: buf.readUInt16LE(26) & 0x3fff,
+      height: buf.readUInt16LE(28) & 0x3fff,
+    }
+  }
+  return undefined
+}
+
+/**
+ * Read image pixel dimensions from a PNG or WebP buffer. Returns undefined
+ * for formats this reader does not recognize (never throws). Callers treat
+ * undefined as "cannot verify", not as an error.
+ */
+export function imageDimensions(buf: Buffer): ImageDimensions | undefined {
+  if (buf.length >= 12 && buf.toString('ascii', 0, 4) === 'RIFF') return webpDimensions(buf)
+  return pngDimensions(buf)
+}

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
@@ -170,7 +172,7 @@ function applyImpl(ctx: Context, config: PetConfig = {}): void {
   // pattern as dsh-remote-web-ui's /api/pair family). The routes are
   // registered while the plugin is enabled; toggling the setting off makes
   // the pet API disappear until it is re-enabled.
-  const routes = makePetRoutes({ service })
+  const routes = makePetRoutes({ service, ctx })
   let disposeRoutes: (() => void) | undefined
   const syncRoutes = (): void => {
     const enabled = current().enabled ?? true