@linxin666/dsh-pet 0.2.3 → 0.2.5

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

@@ -20,7 +20,10 @@ import { createPhaseStream, type PhaseStream } from '../phase-stream.ts'
 import type { PetRendererContext } from '../../contracts/renderer.ts'
 
 interface FakeModel {
+  automator: { autoUpdate: boolean }
   calls: unknown[][]
+  destroyCalls: Record<string, unknown>[]
+  destroyed: number
   listeners: Record<string, () => void>
   width: number
   height: number
@@ -32,21 +35,58 @@ interface FakeModel {
   expression(name?: string): void
   hitTest(x: number, y: number): string[]
   on(event: string, fn: () => void): void
+  destroy(options?: Record<string, unknown>): void
 }
 
 interface FakeApp {
   canvas: HTMLCanvasElement
   stage: { addChild(child: unknown): void }
-  renderer: { width: number; height: number }
+  renderer: { width: number; height: number; resize(width: number, height: number): void }
   init(options: Record<string, unknown>): Promise<void>
-  destroy(): void
+  destroy(rendererOptions?: boolean | { removeView?: boolean; releaseGlobalResources?: boolean }, options?: Record<string, unknown>): void
   destroyed: number
+  destroyCalls: unknown[][]
   added: unknown
+  resizeCalls: [number, number][]
+}
+
+class FakeResizeObserver {
+  static instances: FakeResizeObserver[] = []
+
+  readonly targets = new Set<Element>()
+  disconnected = false
+
+  constructor(private readonly callback: ResizeObserverCallback) {
+    FakeResizeObserver.instances.push(this)
+  }
+
+  observe(target: Element): void {
+    this.targets.add(target)
+  }
+
+  unobserve(target: Element): void {
+    this.targets.delete(target)
+  }
+
+  disconnect(): void {
+    this.disconnected = true
+    this.targets.clear()
+  }
+
+  emit(target: Element, width: number, height: number): void {
+    this.callback([{
+      target,
+      contentRect: { width, height },
+    } as ResizeObserverEntry], this as unknown as ResizeObserver)
+  }
 }
 
 function fakeModel(motions: Record<string, unknown[]> = { Idle: [{}, {}], TapBody: [{}] }): FakeModel {
   const model: FakeModel = {
+    automator: { autoUpdate: false },
     calls: [],
+    destroyCalls: [],
+    destroyed: 0,
     listeners: {},
     width: 1000,
     height: 1200,
@@ -58,41 +98,94 @@ function fakeModel(motions: Record<string, unknown[]> = { Idle: [{}, {}], TapBod
     expression: (name) => { model.calls.push(['expression', name]) },
     hitTest: (x, y) => { model.calls.push(['hitTest', x, y]); return ['Body'] },
     on: (event, fn) => { model.listeners[event] = fn },
+    destroy: (options = {}) => {
+      model.destroyed += 1
+      model.destroyCalls.push(options)
+      model.automator.autoUpdate = false
+    },
   }
   return model
 }
 
 function fakeApp(): FakeApp {
+  const canvas = document.createElement('canvas')
   const app: FakeApp = {
-    canvas: document.createElement('canvas'),
+    canvas,
     stage: { addChild: (child) => { app.added = child } },
-    renderer: { width: 160, height: 174 },
-    init: () => Promise.resolve(),
-    destroy: () => { app.destroyed += 1 },
+    renderer: {
+      width: 160,
+      height: 174,
+      resize: (width, height) => {
+        app.renderer.width = width
+        app.renderer.height = height
+        canvas.width = width
+        canvas.height = height
+        app.resizeCalls.push([width, height])
+      },
+    },
+    init: (options) => {
+      app.renderer.width = Number(options.width)
+      app.renderer.height = Number(options.height)
+      canvas.width = app.renderer.width
+      canvas.height = app.renderer.height
+      return Promise.resolve()
+    },
+    destroy: (rendererOptions, options) => {
+      app.destroyed += 1
+      app.destroyCalls.push([rendererOptions, options])
+      if (rendererOptions === true || (typeof rendererOptions === 'object' && rendererOptions.removeView === true)) app.canvas.remove()
+      if (options?.children === true && typeof (app.added as { destroy?: unknown } | undefined)?.destroy === 'function') {
+        ;(app.added as { destroy(options?: Record<string, unknown>): void }).destroy(options)
+      }
+    },
     destroyed: 0,
+    destroyCalls: [],
     added: undefined,
+    resizeCalls: [],
   }
   return app
 }
 
-function fakeVendor(model: FakeModel, app: FakeApp): unknown {
+function fakeVendor(
+  model: FakeModel,
+  app: FakeApp,
+  from: (source: string, options?: Record<string, unknown>) => Promise<FakeModel> = (_source, options) => {
+    model.calls.push(['from', options])
+    return Promise.resolve(model)
+  },
+): unknown {
   return {
     Application: class { constructor() { return app } },
     extensions: { add: () => {} },
     Live2DPlugin: {},
     configureCubismSDK: () => {},
-    Live2DModel: { from: () => Promise.resolve(model) },
+    Live2DModel: { from },
   }
 }
 
 const CONFIG = { modelUrl: '/pet/haru/haru.model3.json', motions: { idle: 'Idle', thinking: 'TapBody' } }
 
-function makeCtx(): { ctx: PetRendererContext; stream: PhaseStream; container: HTMLDivElement } {
+function makeCtx(width = 0, height = 0): {
+  ctx: PetRendererContext
+  stream: PhaseStream
+  container: HTMLDivElement
+  setSize(nextWidth: number, nextHeight: number): void
+} {
   const container = document.createElement('div')
+  let clientWidth = width
+  let clientHeight = height
+  Object.defineProperties(container, {
+    clientWidth: { configurable: true, get: () => clientWidth },
+    clientHeight: { configurable: true, get: () => clientHeight },
+  })
   const stream = createPhaseStream('idle')
   return {
     container,
     stream,
+    setSize(nextWidth, nextHeight) {
+      clientWidth = nextWidth
+      clientHeight = nextHeight
+    },
     ctx: {
       petId: 'haru',
       assetBase: '/pet/haru',
@@ -111,9 +204,12 @@ async function flush(): Promise<void> {
 describe('live2dRenderer', () => {
   beforeEach(() => {
     runtime.core = true
+    FakeResizeObserver.instances = []
+    vi.stubGlobal('ResizeObserver', FakeResizeObserver)
     resetLive2dRenderer()
   })
   afterEach(() => {
+    vi.unstubAllGlobals()
     vi.restoreAllMocks()
   })
 
@@ -127,6 +223,8 @@ describe('live2dRenderer', () => {
     await flush()
     expect(container.querySelector('canvas')).toBeTruthy()
     expect(app.added).toBe(model)
+    expect(model.calls).toContainEqual(['from', expect.objectContaining({ autoUpdate: false, autoHitTest: false, autoFocus: false })])
+    expect(model.automator.autoUpdate).toBe(true)
     // idle plays on boot: group 'Idle', random index floor(0.99 * 2) = 1.
     expect(model.calls).toContainEqual(['motion', 'Idle', 1])
     // auto-fit: min(160/1000, 174/1200) * 0.92 = 0.1334
@@ -138,8 +236,98 @@ describe('live2dRenderer', () => {
     expect(model.calls.filter(call => call[0] === 'motion').at(-1)).toEqual(['motion', 'Idle', 1])
     handle.dispose()
     expect(app.destroyed).toBe(1)
+    expect(app.destroyCalls[0]?.[0]).toEqual({ removeView: true })
+    expect(model.destroyed).toBe(1)
+    expect(model.destroyCalls).toContainEqual({ children: true })
+    expect(model.automator.autoUpdate).toBe(false)
     handle.dispose() // idempotent
     expect(app.destroyed).toBe(1)
+    expect(app.destroyCalls[0]?.[0]).toEqual({ removeView: true })
+    expect(model.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, {
+      autoUpdate: false,
+      autoHitTest: false,
+      autoFocus: false,
+      textureOptions: { lod: 'single-auto' },
+    })
+  })
+
+  it('keeps the Pixi canvas and model layout in sync with display-size changes', async () => {
+    const model = fakeModel()
+    const app = fakeApp()
+    runtime.vendor = fakeVendor(model, app)
+    const { ctx, container, setSize } = makeCtx(148, 160)
+
+    const handle = live2dRenderer.mount(ctx, live2dRenderer.validateConfig(CONFIG)) as Live2dRendererHandle
+    await flush()
+    expect(app.canvas.width).toBe(148)
+    expect(app.canvas.height).toBe(160)
+    expect(model.calls).toContainEqual(['position', 74, 80])
+
+    model.calls.length = 0
+    setSize(295, 320)
+    FakeResizeObserver.instances[0]?.emit(container, 295, 320)
+
+    expect(app.resizeCalls).toEqual([[295, 320]])
+    expect(app.canvas.width).toBe(295)
+    expect(app.canvas.height).toBe(320)
+    expect(model.calls).toContainEqual(['scale', expect.closeTo(0.245333, 5)])
+    expect(model.calls).toContainEqual(['position', 147.5, 160])
+    handle.tap(147.5, 160)
+    expect(model.calls).toContainEqual(['hitTest', 147.5, 160])
+
+    handle.dispose()
+    expect(FakeResizeObserver.instances[0]?.disconnected).toBe(true)
+  })
+
+  it('uses the latest renderer size when the model finishes loading', async () => {
+    const model = fakeModel()
+    const app = fakeApp()
+    let resolveModel!: (value: FakeModel) => void
+    const pendingModel = new Promise<FakeModel>((resolve) => { resolveModel = resolve })
+    runtime.vendor = fakeVendor(model, app, () => pendingModel)
+    const { ctx, container, setSize } = makeCtx(148, 160)
+
+    live2dRenderer.mount(ctx, live2dRenderer.validateConfig(CONFIG))
+    await flush()
+    setSize(295, 320)
+    FakeResizeObserver.instances[0]?.emit(container, 295, 320)
+    resolveModel(model)
+    await flush()
+
+    expect(app.resizeCalls).toEqual([[295, 320]])
+    expect(model.calls).toContainEqual(['position', 147.5, 160])
+    expect(model.calls).toContainEqual(['scale', expect.closeTo(0.245333, 5)])
+  })
+
+  it('ignores zero-size observations and stops resizing after disposal', async () => {
+    const model = fakeModel()
+    const app = fakeApp()
+    runtime.vendor = fakeVendor(model, app)
+    const { ctx, container } = makeCtx(148, 160)
+    const handle = live2dRenderer.mount(ctx, live2dRenderer.validateConfig(CONFIG))
+    await flush()
+    const observer = FakeResizeObserver.instances[0]
+
+    observer?.emit(container, 0, 0)
+    observer?.emit(container, 148, 160)
+    expect(app.resizeCalls).toEqual([])
+
+    handle.dispose()
+    observer?.emit(container, 295, 320)
+    expect(app.resizeCalls).toEqual([])
   })
 
   it('falls back to the idle group when a mapped group is absent from the model', async () => {
@@ -218,7 +406,43 @@ describe('live2dRenderer', () => {
     handle.onError((next) => { code = next })
     await flush()
     expect(code).toBe('load-failed')
+    expect(app.destroyed).toBe(1)
+    expect(ctx.container.querySelector('canvas')).toBeNull()
     handle.dispose()
+    expect(app.destroyed).toBe(1)
+  })
+
+  it('destroys both sides exactly once when disposed while model loading is pending', async () => {
+    const model = fakeModel()
+    const app = fakeApp()
+    let resolveModel!: (value: FakeModel) => void
+    const pendingModel = new Promise<FakeModel>((resolve) => { resolveModel = resolve })
+    const from = vi.fn(() => pendingModel)
+    runtime.vendor = {
+      Application: class { constructor() { return app } },
+      extensions: { add: () => {} },
+      Live2DPlugin: {},
+      configureCubismSDK: () => {},
+      Live2DModel: { from },
+    }
+    const { ctx, container } = makeCtx()
+    const handle = live2dRenderer.mount(ctx, live2dRenderer.validateConfig(CONFIG))
+    let error: string | undefined
+    ;(handle as Live2dRendererHandle).onError((code) => { error = code })
+    await flush()
+    expect(from).toHaveBeenCalledTimes(1)
+    expect(container.querySelector('canvas')).toBeTruthy()
+    handle.dispose()
+    expect(app.destroyed).toBe(1)
+    expect(container.querySelector('canvas')).toBeNull()
+    resolveModel(model)
+    await flush()
+    expect(app.destroyed).toBe(1)
+    expect(model.destroyed).toBe(1)
+    expect(model.destroyCalls).toContainEqual({ children: true })
+    expect(model.automator.autoUpdate).toBe(false)
+    expect(app.added).toBeUndefined()
+    expect(error).toBeUndefined()
   })
 
   it('never appends a canvas when disposed mid-boot', async () => {

package/src/client/renderers/live2d.ts

@@ -60,6 +60,52 @@ 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
+/** Recursively release the activation without invalidating shared texture caches. */
+const DESTROY_OPTIONS = { children: true } as const
+/** Remove only this activation's canvas; `true` would release Pixi globals. */
+const RENDERER_DESTROY_OPTIONS = { removeView: true } as const
+
+interface Live2dModelSize {
+  width: number
+  height: number
+}
+
+/** Ignore hidden/zero boxes and keep Pixi dimensions stable and integral. */
+function normalizeRendererSize(width: number, height: number): Live2dModelSize | undefined {
+  if (!Number.isFinite(width) || !Number.isFinite(height) || width <= 0 || height <= 0) return undefined
+  return {
+    width: Math.max(1, Math.round(width)),
+    height: Math.max(1, Math.round(height)),
+  }
+}
+
+/** Fit the model from its unscaled dimensions into the current Pixi screen. */
+function layoutModel(
+  app: Live2dVendorApp,
+  model: Live2dVendorModel,
+  sourceSize: Live2dModelSize,
+  config: PetLive2dConfig,
+): void {
+  const fit = Math.min(
+    app.renderer.width / sourceSize.width,
+    app.renderer.height / sourceSize.height,
+  ) * 0.92
+  model.scale.set(fit * (config.scale ?? 1))
+  model.anchor.set(0.5)
+  model.position.set(
+    app.renderer.width / 2 + (config.translate?.x ?? 0),
+    app.renderer.height / 2 + (config.translate?.y ?? 0),
+  )
+}
+
 let vendorConfigured = false
 
 /** Configure pixi extensions + the Cubism SDK once per page. */
@@ -96,12 +142,64 @@ export const live2dRenderer: PetRenderer<PetLive2dConfig> = {
     let disposed = false
     let app: Live2dVendorApp | undefined
     let model: Live2dVendorModel | undefined
+    let modelAttached = false
+    let modelSourceSize: Live2dModelSize | undefined
+    let resizeObserver: ResizeObserver | undefined
+    let resizeTracking = false
     let errorListener: ((code: Live2dErrorCode) => void) | undefined
     let unsubscribe: (() => void) | undefined
     /** The motion group the current phase maps to (resume target after taps). */
     let phaseGroup: string = config.motions.idle
     let tapPlaying = false
 
+    const stopResizeTracking = (): void => {
+      resizeTracking = false
+      resizeObserver?.disconnect()
+      resizeObserver = undefined
+    }
+
+    const resizeRenderer = (pixiApp: Live2dVendorApp, width: number, height: number): void => {
+      const next = normalizeRendererSize(width, height)
+      if (disposed || !resizeTracking || next === undefined) return
+      if (pixiApp.renderer.width === next.width && pixiApp.renderer.height === next.height) return
+      pixiApp.renderer.resize(next.width, next.height)
+      if (model !== undefined && modelSourceSize !== undefined) {
+        layoutModel(pixiApp, model, modelSourceSize, config)
+      }
+    }
+
+    const trackContainerSize = (pixiApp: Live2dVendorApp): void => {
+      if (typeof ResizeObserver === 'undefined') return
+      resizeTracking = true
+      resizeObserver = new ResizeObserver((entries) => {
+        const entry = entries.find(candidate => candidate.target === ctx.container)
+        if (entry === undefined) return
+        resizeRenderer(pixiApp, entry.contentRect.width, entry.contentRect.height)
+      })
+      resizeObserver.observe(ctx.container)
+      // Catch a synchronous layout change between init() and observe().
+      resizeRenderer(pixiApp, ctx.container.clientWidth, ctx.container.clientHeight)
+    }
+
+    /** Release every resource currently owned by this activation exactly once. */
+    const destroyResources = (): void => {
+      stopResizeTracking()
+      unsubscribe?.()
+      unsubscribe = undefined
+      const currentApp = app
+      const currentModel = model
+      const modelOwnedByApp = currentApp !== undefined && modelAttached
+      app = undefined
+      model = undefined
+      modelSourceSize = undefined
+      modelAttached = false
+      try {
+        if (currentModel !== undefined && !modelOwnedByApp) currentModel.destroy(DESTROY_OPTIONS)
+      } finally {
+        currentApp?.destroy(RENDERER_DESTROY_OPTIONS, DESTROY_OPTIONS)
+      }
+    }
+
     const playGroup = (group: string): void => {
       if (model === undefined) return
       const groups = model.internalModel.settings.motions ?? {}
@@ -134,42 +232,58 @@ export const live2dRenderer: PetRenderer<PetLive2dConfig> = {
       }
       configureOnce(vendor)
       const pixiApp = new vendor.Application()
-      await pixiApp.init({
-        width: Math.max(1, ctx.container.clientWidth || 160),
-        height: Math.max(1, ctx.container.clientHeight || 174),
-        backgroundAlpha: 0,
-        antialias: true,
-        autoDensity: true,
-        preference: 'webgl',
-      })
+      const initialSize = normalizeRendererSize(ctx.container.clientWidth, ctx.container.clientHeight) ?? {
+        width: 160,
+        height: 174,
+      }
+      try {
+        await pixiApp.init({
+          width: initialSize.width,
+          height: initialSize.height,
+          backgroundAlpha: 0,
+          antialias: true,
+          autoDensity: true,
+          preference: 'webgl',
+        })
+      } catch (error) {
+        // init() can fail after allocating a partial renderer; cleanup is
+        // best-effort because Pixi may not consider that partial app ready.
+        try { pixiApp.destroy(RENDERER_DESTROY_OPTIONS, DESTROY_OPTIONS) } catch {}
+        throw error
+      }
       if (disposed) {
-        pixiApp.destroy(true, { children: true })
+        pixiApp.destroy(RENDERER_DESTROY_OPTIONS, DESTROY_OPTIONS)
         return
       }
+      app = pixiApp
       pixiApp.canvas.style.display = 'block'
       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 })
+      // Keep a model that rejects during setup off Ticker.shared; from()
+      // does not expose that partial instance to callers for disposal.
+      trackContainerSize(pixiApp)
+      const loaded = await vendor.Live2DModel.from(config.modelUrl, {
+        autoUpdate: false,
+        autoHitTest: false,
+        autoFocus: false,
+        textureOptions: TEXTURE_OPTIONS,
+      })
+      model = loaded
       if (disposed) {
-        pixiApp.destroy(true, { children: true })
+        destroyResources()
         return
       }
-      app = pixiApp
-      model = loaded
+      modelSourceSize = {
+        width: Math.max(1, loaded.width),
+        height: Math.max(1, loaded.height),
+      }
       // Auto-fit the model into the container; the manifest scale multiplies
       // the fit and translate offsets from the center anchor.
-      const fit = Math.min(
-        pixiApp.renderer.width / Math.max(1, loaded.width),
-        pixiApp.renderer.height / Math.max(1, loaded.height),
-      ) * 0.92
-      loaded.scale.set(fit * (config.scale ?? 1))
-      loaded.anchor.set(0.5)
-      loaded.position.set(
-        pixiApp.renderer.width / 2 + (config.translate?.x ?? 0),
-        pixiApp.renderer.height / 2 + (config.translate?.y ?? 0),
-      )
+      layoutModel(pixiApp, loaded, modelSourceSize, config)
       pixiApp.stage.addChild(loaded)
+      modelAttached = true
+      loaded.automator.autoUpdate = true
       // Resume the phase group once a tap motion finishes playing.
       loaded.on('motionFinish', () => {
         if (tapPlaying) {
@@ -182,19 +296,18 @@ export const live2dRenderer: PetRenderer<PetLive2dConfig> = {
     }
 
     void boot().catch(() => {
-      if (!disposed) errorListener?.('load-failed')
+      try {
+        destroyResources()
+      } finally {
+        if (!disposed) errorListener?.('load-failed')
+      }
     })
 
     return {
       dispose() {
         if (disposed) return
         disposed = true
-        unsubscribe?.()
-        model = undefined
-        if (app !== undefined) {
-          app.destroy(true, { children: true })
-          app = undefined
-        }
+        destroyResources()
       },
       tap(x: number, y: number) {
         const current = model

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