@linxin666/dsh-pet 0.2.2 → 0.2.4

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

@@ -0,0 +1,263 @@
+// @vitest-environment jsdom
+/**
+ * Live2D renderer unit tests (pet-center M3, issue #623) — the vendor stack
+ * is faked structurally (no pixi, no WebGL in jsdom); the runtime loader is
+ * module-mocked so script injection never happens.
+ */
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+const runtime = vi.hoisted(() => ({
+  core: true as boolean,
+  vendor: undefined as unknown,
+}))
+vi.mock('./live2d/runtime.ts', () => ({
+  ensureCubismCore: () => Promise.resolve(runtime.core),
+  ensureLive2dVendor: () => Promise.resolve(runtime.vendor),
+}))
+
+import { live2dRenderer, resetLive2dRenderer, type Live2dRendererHandle } from './live2d.ts'
+import { createPhaseStream, type PhaseStream } from '../phase-stream.ts'
+import type { PetRendererContext } from '../../contracts/renderer.ts'
+
+interface FakeModel {
+  calls: unknown[][]
+  listeners: Record<string, () => void>
+  width: number
+  height: number
+  anchor: { set(x: number, y?: number): void }
+  position: { set(x: number, y: number): void }
+  scale: { set(x: number, y?: number): void }
+  internalModel: { settings: { motions: Record<string, unknown[]>; hitAreas: { Name: string }[] } }
+  motion(group: string, index?: number): Promise<boolean>
+  expression(name?: string): void
+  hitTest(x: number, y: number): string[]
+  on(event: string, fn: () => void): void
+}
+
+interface FakeApp {
+  canvas: HTMLCanvasElement
+  stage: { addChild(child: unknown): void }
+  renderer: { width: number; height: number }
+  init(options: Record<string, unknown>): Promise<void>
+  destroy(): void
+  destroyed: number
+  added: unknown
+}
+
+function fakeModel(motions: Record<string, unknown[]> = { Idle: [{}, {}], TapBody: [{}] }): FakeModel {
+  const model: FakeModel = {
+    calls: [],
+    listeners: {},
+    width: 1000,
+    height: 1200,
+    anchor: { set: (...args) => { model.calls.push(['anchor', ...args]) } },
+    position: { set: (...args) => { model.calls.push(['position', ...args]) } },
+    scale: { set: (...args) => { model.calls.push(['scale', ...args]) } },
+    internalModel: { settings: { motions, hitAreas: [{ Name: 'Body' }] } },
+    motion: (group, index) => { model.calls.push(['motion', group, index]); return Promise.resolve(true) },
+    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 },
+  }
+  return model
+}
+
+function fakeApp(): FakeApp {
+  const app: FakeApp = {
+    canvas: document.createElement('canvas'),
+    stage: { addChild: (child) => { app.added = child } },
+    renderer: { width: 160, height: 174 },
+    init: () => Promise.resolve(),
+    destroy: () => { app.destroyed += 1 },
+    destroyed: 0,
+    added: undefined,
+  }
+  return app
+}
+
+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 },
+  }
+}
+
+const CONFIG = { modelUrl: '/pet/haru/haru.model3.json', motions: { idle: 'Idle', thinking: 'TapBody' } }
+
+function makeCtx(): { ctx: PetRendererContext; stream: PhaseStream; container: HTMLDivElement } {
+  const container = document.createElement('div')
+  const stream = createPhaseStream('idle')
+  return {
+    container,
+    stream,
+    ctx: {
+      petId: 'haru',
+      assetBase: '/pet/haru',
+      container,
+      phase: stream,
+      interact: () => {},
+      onCleanup: () => {},
+    },
+  }
+}
+
+async function flush(): Promise<void> {
+  for (let index = 0; index < 20; index += 1) await Promise.resolve()
+}
+
+describe('live2dRenderer', () => {
+  beforeEach(() => {
+    runtime.core = true
+    resetLive2dRenderer()
+  })
+  afterEach(() => {
+    vi.restoreAllMocks()
+  })
+
+  it('boots the model and maps phases onto motion groups with idle fallback', async () => {
+    const model = fakeModel()
+    const app = fakeApp()
+    runtime.vendor = fakeVendor(model, app)
+    vi.spyOn(Math, 'random').mockReturnValue(0.99)
+    const { ctx, stream, container } = makeCtx()
+    const handle = live2dRenderer.mount(ctx, live2dRenderer.validateConfig(CONFIG))
+    await flush()
+    expect(container.querySelector('canvas')).toBeTruthy()
+    expect(app.added).toBe(model)
+    // 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
+    const scaleCall = model.calls.find(call => call[0] === 'scale')
+    expect(scaleCall?.[1]).toBeCloseTo(0.145 * 0.92, 4)
+    stream.push('thinking')
+    expect(model.calls).toContainEqual(['motion', 'TapBody', 0])
+    stream.push('tool') // unmapped phase falls back to idle
+    expect(model.calls.filter(call => call[0] === 'motion').at(-1)).toEqual(['motion', 'Idle', 1])
+    handle.dispose()
+    expect(app.destroyed).toBe(1)
+    handle.dispose() // idempotent
+    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())
+    const { ctx, stream } = makeCtx()
+    live2dRenderer.mount(ctx, live2dRenderer.validateConfig({ ...CONFIG, motions: { idle: 'Idle', done: 'Nope' } }))
+    await flush()
+    model.calls.length = 0
+    stream.push('done')
+    expect(model.calls).toContainEqual(['motion', 'Idle', 0])
+  })
+
+  it('layers the phase expression when the manifest declares one', async () => {
+    const model = fakeModel()
+    runtime.vendor = fakeVendor(model, fakeApp())
+    const { ctx, stream } = makeCtx()
+    live2dRenderer.mount(ctx, live2dRenderer.validateConfig({ ...CONFIG, expressions: { thinking: 'F01' } }))
+    await flush()
+    stream.push('thinking')
+    expect(model.calls).toContainEqual(['expression', 'F01'])
+  })
+
+  it('plays the tap group on a declared hit area and resumes the phase group on finish', async () => {
+    const model = fakeModel()
+    runtime.vendor = fakeVendor(model, fakeApp())
+    const { ctx } = makeCtx()
+    const handle = live2dRenderer.mount(ctx, live2dRenderer.validateConfig({ ...CONFIG, hitAreas: ['Body'] })) as Live2dRendererHandle
+    await flush()
+    model.calls.length = 0
+    handle.tap(40, 60)
+    expect(model.calls).toContainEqual(['hitTest', 40, 60])
+    expect(model.calls).toContainEqual(['motion', 'TapBody', 0])
+    model.calls.length = 0
+    model.listeners.motionFinish?.()
+    expect(model.calls).toContainEqual(['motion', 'Idle', expect.any(Number)])
+  })
+
+  it('ignores taps outside the declared hit areas', async () => {
+    const model = fakeModel()
+    runtime.vendor = fakeVendor(model, fakeApp())
+    const { ctx } = makeCtx()
+    const handle = live2dRenderer.mount(ctx, live2dRenderer.validateConfig({ ...CONFIG, hitAreas: ['Head'] })) as Live2dRendererHandle
+    await flush()
+    model.calls.length = 0
+    handle.tap(10, 10)
+    expect(model.calls).toContainEqual(['hitTest', 10, 10])
+    expect(model.calls.some(call => call[0] === 'motion')).toBe(false)
+  })
+
+  it('reports core-missing when the user has not installed the Cubism Core', async () => {
+    runtime.core = false
+    runtime.vendor = fakeVendor(fakeModel(), fakeApp())
+    const { ctx } = makeCtx()
+    let code: string | undefined
+    const handle = live2dRenderer.mount(ctx, live2dRenderer.validateConfig(CONFIG)) as Live2dRendererHandle
+    handle.onError((next) => { code = next })
+    await flush()
+    expect(code).toBe('core-missing')
+    handle.dispose()
+  })
+
+  it('reports load-failed when the model fetch rejects', async () => {
+    const model = fakeModel()
+    const app = fakeApp()
+    runtime.vendor = {
+      Application: class { constructor() { return app } },
+      extensions: { add: () => {} },
+      Live2DPlugin: {},
+      configureCubismSDK: () => {},
+      Live2DModel: { from: () => Promise.reject(new Error('404')) },
+    }
+    const { ctx } = makeCtx()
+    let code: string | undefined
+    const handle = live2dRenderer.mount(ctx, live2dRenderer.validateConfig(CONFIG)) as Live2dRendererHandle
+    handle.onError((next) => { code = next })
+    await flush()
+    expect(code).toBe('load-failed')
+    handle.dispose()
+  })
+
+  it('never appends a canvas when disposed mid-boot', async () => {
+    const model = fakeModel()
+    const app = fakeApp()
+    runtime.vendor = fakeVendor(model, app)
+    const { ctx, container } = makeCtx()
+    const handle = live2dRenderer.mount(ctx, live2dRenderer.validateConfig(CONFIG))
+    handle.dispose()
+    await flush()
+    expect(container.querySelector('canvas')).toBeNull()
+    // The app created mid-boot is destroyed exactly once (no leak), never twice.
+    expect(app.destroyed).toBe(1)
+  })
+
+  it('validateConfig is fail-closed', () => {
+    expect(() => live2dRenderer.validateConfig({})).toThrow('modelUrl')
+    expect(() => live2dRenderer.validateConfig({ modelUrl: '/x' })).toThrow('motions.idle')
+    expect(live2dRenderer.validateConfig(CONFIG)).toBe(CONFIG)
+  })
+})

package/src/client/renderers/live2d.ts

@@ -0,0 +1,231 @@
+/**
+ * Live2D renderer (pet-center M3, issue #623) — mounts a Cubism model into
+ * the center-owned container through the lazy vendor stack. The mount call
+ * itself is synchronous per the renderer contract: the boot (core script →
+ * vendor script → pixi → model) continues asynchronously and reports fatal
+ * failures through the handle's error sink, so the React bridge can render
+ * localized guidance. Disposing mid-boot is race-safe.
+ *
+ * Interaction model: the center chrome owns the affinity economy (its click
+ * handler fires the pet interaction exactly like sprite2d); this renderer's
+ * 'tap' affordance only drives the model's hit-area motion feedback. The
+ * contract's interact write-back stays available for future standalone
+ * mounts and is intentionally not invoked here.
+ *
+ * Motion mapping: manifests map ActivityPhases to motion GROUP names; every
+ * unmapped phase (and any mapped-but-absent group) falls back to the idle
+ * group — official sample models only ship Idle/TapBody, so the fallback is
+ * mandatory. Groups with multiple motions pick a random entry, and a tap
+ * that hits a declared hit area plays the conventional 'TapBody' group,
+ * returning to the phase's group when the tap motion finishes.
+ * @module @linxin666/dsh-pet/client/renderers/live2d
+ */
+
+import type { ActivityPhase } from '../../state.ts'
+import {
+  PET_RENDERER_API_VERSION,
+  type PetRenderer,
+  type PetRendererContext,
+  type PetRendererHandle,
+} from '../../contracts/renderer.ts'
+import {
+  ensureCubismCore,
+  ensureLive2dVendor,
+  type Live2dVendor,
+  type Live2dVendorApp,
+  type Live2dVendorModel,
+} from './live2d/runtime.ts'
+
+/** Renderer config: the client-visible live2d block (fail-closed validated). */
+export interface PetLive2dConfig {
+  modelUrl: string
+  scale?: number
+  translate?: { x?: number; y?: number }
+  motions: Partial<Record<ActivityPhase, string>> & { idle: string }
+  expressions?: Partial<Record<ActivityPhase, string>>
+  hitAreas?: string[]
+}
+
+/** Fatal mount failure codes the bridge localizes. */
+export type Live2dErrorCode = 'core-missing' | 'vendor-missing' | 'load-failed'
+
+/** The live2d activation handle: contract dispose plus tap + error sink. */
+export interface Live2dRendererHandle extends PetRendererHandle {
+  /** Forward a chrome tap in container coordinates; plays the hit motion. */
+  tap(x: number, y: number): void
+  /** Subscribe to fatal mount errors (at most one fires per activation). */
+  onError(listener: (code: Live2dErrorCode) => void): void
+}
+
+/** 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. */
+function configureOnce(vendor: Live2dVendor): void {
+  if (vendorConfigured) return
+  vendorConfigured = true
+  vendor.extensions.add(vendor.Live2DPlugin)
+  vendor.configureCubismSDK({ memorySizeMB: 32 })
+}
+
+/** Reset module state (tests). */
+export function resetLive2dRenderer(): void {
+  vendorConfigured = false
+}
+
+/** Fail-closed config validation (contract: unknown manifest block in). */
+function validateLive2dConfig(config: unknown): PetLive2dConfig {
+  if (typeof config !== 'object' || config === null) throw new Error('live2d config is not an object')
+  const source = config as Record<string, unknown>
+  if (typeof source.modelUrl !== 'string' || source.modelUrl === '') throw new Error('live2d config modelUrl is required')
+  const motions = source.motions
+  if (typeof motions !== 'object' || motions === null || typeof (motions as Record<string, unknown>).idle !== 'string') {
+    throw new Error('live2d config motions.idle is required')
+  }
+  return config as PetLive2dConfig
+}
+
+/** The live2d renderer implementation. */
+export const live2dRenderer: PetRenderer<PetLive2dConfig> = {
+  id: 'live2d',
+  apiVersion: PET_RENDERER_API_VERSION,
+  validateConfig: validateLive2dConfig,
+  mount(ctx: PetRendererContext, config: PetLive2dConfig): Live2dRendererHandle {
+    let disposed = false
+    let app: Live2dVendorApp | undefined
+    let model: Live2dVendorModel | undefined
+    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 playGroup = (group: string): void => {
+      if (model === undefined) return
+      const groups = model.internalModel.settings.motions ?? {}
+      const count = Array.isArray(groups[group]) ? groups[group]!.length : 0
+      if (count === 0) {
+        // A mapped-but-absent group falls back to idle (never blank motion).
+        if (group !== config.motions.idle) playGroup(config.motions.idle)
+        return
+      }
+      const index = count > 1 ? Math.floor(Math.random() * count) : 0
+      void model.motion(group, index)
+    }
+
+    const applyPhase = (phase: ActivityPhase): void => {
+      phaseGroup = config.motions[phase] ?? config.motions.idle
+      playGroup(phaseGroup)
+      const expression = config.expressions?.[phase]
+      if (expression !== undefined && model !== undefined) void model.expression(expression)
+    }
+
+    const boot = async (): Promise<void> => {
+      if (!await ensureCubismCore()) {
+        if (!disposed) errorListener?.('core-missing')
+        return
+      }
+      const vendor = await ensureLive2dVendor()
+      if (vendor === undefined) {
+        if (!disposed) errorListener?.('vendor-missing')
+        return
+      }
+      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',
+      })
+      if (disposed) {
+        pixiApp.destroy(true, { children: true })
+        return
+      }
+      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,
+        textureOptions: TEXTURE_OPTIONS,
+      })
+      if (disposed) {
+        pixiApp.destroy(true, { children: true })
+        return
+      }
+      app = pixiApp
+      model = loaded
+      // 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),
+      )
+      pixiApp.stage.addChild(loaded)
+      // Resume the phase group once a tap motion finishes playing.
+      loaded.on('motionFinish', () => {
+        if (tapPlaying) {
+          tapPlaying = false
+          playGroup(phaseGroup)
+        }
+      })
+      applyPhase(ctx.phase.get())
+      unsubscribe = ctx.phase.subscribe(applyPhase)
+    }
+
+    void boot().catch(() => {
+      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
+        }
+      },
+      tap(x: number, y: number) {
+        const current = model
+        if (disposed || current === undefined) return
+        const hits = current.hitTest(x, y)
+        const allowed = config.hitAreas
+        const hit = allowed === undefined ? hits.length > 0 : hits.some(name => allowed.includes(name))
+        if (!hit) return
+        const groups = current.internalModel.settings.motions ?? {}
+        const group = groups[TAP_GROUP]
+        if (!Array.isArray(group) || group.length === 0) return
+        tapPlaying = true
+        const index = group.length > 1 ? Math.floor(Math.random() * group.length) : 0
+        void current.motion(TAP_GROUP, index)
+      },
+      onError(listener: (code: Live2dErrorCode) => void) {
+        errorListener = listener
+      },
+    }
+  },
+}

package/src/client/renderers/registry.ts

@@ -0,0 +1,58 @@
+/**
+ * Renderer registry — dispatches a manifest's renderer kind to its
+ * implementation (pet-center M2 P4, issue #623). Unknown kinds never blank
+ * the pet: a fallback card names the problem and reports the kinds this
+ * build actually supports.
+ * @module @linxin666/dsh-pet/client/renderers/registry
+ */
+
+import type { PetRenderer, PetRendererContext, PetRendererHandle } from '../../contracts/renderer.ts'
+
+/** Renderer dispatch table. */
+export class RendererRegistry {
+  private readonly renderers = new Map<string, PetRenderer>()
+
+  /** Register one renderer implementation (id wins on re-register). */
+  register(renderer: PetRenderer): void {
+    this.renderers.set(renderer.id, renderer)
+  }
+
+  /** Whether a renderer kind is available in this build. */
+  has(id: string): boolean {
+    return this.renderers.has(id)
+  }
+
+  /** The registered renderer kinds (for diagnostics). */
+  kinds(): string[] {
+    return [...this.renderers.keys()].sort()
+  }
+
+  /** Remove every registration (tests; the client index registers once). */
+  clear(): void {
+    this.renderers.clear()
+  }
+
+  /**
+   * Mount a renderer for one activation. An unknown kind renders a clear
+   * diagnostic card into the container instead of failing silently.
+   */
+  mount(kind: string, ctx: PetRendererContext, config: unknown): PetRendererHandle {
+    const renderer = this.renderers.get(kind)
+    if (renderer === undefined) {
+      const note = document.createElement('div')
+      note.dataset.dshPetRendererFallback = kind
+      note.textContent = 'Pet renderer "' + kind + '" is not available in this build (supported: ' + this.kinds().join(', ') + ').'
+      ctx.container.appendChild(note)
+      ctx.onCleanup(() => note.remove())
+      return { dispose: () => note.remove() }
+    }
+    return renderer.mount(ctx, renderer.validateConfig(config))
+  }
+}
+
+/**
+ * The plugin-wide renderer registry. The client entry registers the
+ * built-in renderers at apply time; the renderer switch and the live2d
+ * bridge dispatch through this instance.
+ */
+export const defaultPetRendererRegistry = new RendererRegistry()

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/client/settings-section.module.css

@@ -3,3 +3,26 @@
   margin: 0;
   padding: 0;
 }
+
+/* Registry diagnostics block (pet-center M2 P7, issue #623). */
+.diagnostics {
+  margin: 8px 0;
+  padding: 8px 12px;
+  border: 1px dashed var(--dsw-alias-border-l2);
+  border-radius: 8px;
+  font-size: 12px;
+  color: var(--dsw-alias-label-dimmed);
+}
+.diagnosticsTitle {
+  display: block;
+  font-weight: 600;
+  margin-bottom: 4px;
+  color: var(--dsw-alias-label);
+}
+.diagnostics ul {
+  margin: 0;
+  padding-left: 16px;
+}
+.diagnostics li[data-level="error"] {
+  color: var(--dsw-alias-error, #c04848);
+}

package/src/contracts/renderer.ts

@@ -0,0 +1,54 @@
+/**
+ * Renderer contract — the seam between the pet center and its renderers
+ * (issue #623, milestone M2 P4). Renderers never see the DSH session, the
+ * registry, or the network: they receive exactly three capabilities — an
+ * asset base URL, the ActivityPhase stream, and the interaction write-back —
+ * inside a center-owned container. Every mount is a fresh activation whose
+ * cleanups must be idempotent.
+ *
+ * This contract only serves real consumers: sprite2d (existing) and live2d
+ * (M3). Speculative capabilities join only when a renderer actually needs
+ * them.
+ * @module @linxin666/dsh-pet/contracts/renderer
+ */
+
+import type { ActivityPhase } from '../state.ts'
+
+/** Contract version renderers declare against (independent of the manifest). */
+export const PET_RENDERER_API_VERSION = 'x-org.linxin666.pet-center/v1alpha1'
+
+/** What the pet center hands a renderer on mount. */
+export interface PetRendererContext {
+  /** The selected pet's id. */
+  readonly petId: string
+  /** Same-origin URL prefix of this pet's assets ('/pet/<id>'). */
+  readonly assetBase: string
+  /** Center-owned mount root; renderers must not attach to document.body. */
+  readonly container: HTMLElement
+  /** The ActivityPhase stream (pet-center owned; renderers subscribe). */
+  readonly phase: {
+    get(): ActivityPhase
+    subscribe(listener: (phase: ActivityPhase) => void): () => void
+  }
+  /** The single interaction write-back into the affinity economy. */
+  readonly interact: (kind: 'tap') => void
+  /** Register an activation-scoped cleanup; run on dispose, idempotently. */
+  onCleanup(fn: () => void): void
+}
+
+/** A mounted renderer activation. */
+export interface PetRendererHandle {
+  /** Tear the activation down; may be called 0/1/N times. */
+  dispose(): void
+}
+
+/**
+ * One renderer implementation. validateConfig is fail-closed over the
+ * renderer-specific manifest block (schema v2 'sprite2d'/'live2d' blocks).
+ */
+export interface PetRenderer<Config = unknown> {
+  readonly id: string
+  readonly apiVersion: string
+  validateConfig(config: unknown): Config
+  mount(ctx: PetRendererContext, config: Config): PetRendererHandle
+}