@linxin666/dsh-pet 0.2.1 → 0.2.3

package/src/client/phase-stream.test.ts

@@ -0,0 +1,76 @@
+// @vitest-environment jsdom
+import { describe, expect, it } from 'vitest'
+import { createPhaseStream } from './phase-stream.ts'
+import { RendererRegistry } from './renderers/registry.ts'
+import { PET_RENDERER_API_VERSION, type PetRenderer, type PetRendererContext } from '../contracts/renderer.ts'
+import type { ActivityPhase } from '../state.ts'
+
+describe('createPhaseStream', () => {
+  it('dispatches on change only and supports unsubscribe', () => {
+    const stream = createPhaseStream()
+    const seen: ActivityPhase[] = []
+    const off = stream.subscribe(phase => seen.push(phase))
+    stream.push('idle')       // unchanged: no dispatch
+    stream.push('thinking')
+    stream.push('thinking')   // unchanged: no dispatch
+    stream.push('done')
+    expect(seen).toEqual(['thinking', 'done'])
+    expect(stream.get()).toBe('done')
+    off()
+    stream.push('idle')
+    expect(seen).toHaveLength(2) // no dispatch after unsubscribe
+  })
+})
+
+function fakeContext(): PetRendererContext & { cleanups: Array<() => void> } {
+  const cleanups: Array<() => void> = []
+  return {
+    petId: 'test',
+    assetBase: '/pet/test',
+    container: document.createElement('div'),
+    phase: { get: () => 'idle', subscribe: () => () => {} },
+    interact: () => {},
+    onCleanup: fn => cleanups.push(fn),
+    cleanups,
+  }
+}
+
+describe('RendererRegistry', () => {
+  it('mounts a registered renderer with its validated config', () => {
+    const registry = new RendererRegistry()
+    const calls: unknown[] = []
+    const renderer: PetRenderer<{ tag: string }> = {
+      id: 'sprite2d',
+      apiVersion: PET_RENDERER_API_VERSION,
+      validateConfig: config => ({ tag: String((config as { tag: string }).tag) }),
+      mount: (ctx, config) => {
+        calls.push(config.tag)
+        return { dispose: () => calls.push('disposed') }
+      },
+    }
+    registry.register(renderer)
+    expect(registry.kinds()).toEqual(['sprite2d'])
+    const handle = registry.mount('sprite2d', fakeContext(), { tag: 'hello' })
+    expect(calls).toEqual(['hello'])
+    handle.dispose()
+    expect(calls).toEqual(['hello', 'disposed'])
+  })
+
+  it('renders a diagnostic card for an unknown renderer instead of blanking', () => {
+    const registry = new RendererRegistry()
+    const ctx = fakeContext()
+    const handle = registry.mount('live2d', ctx, {})
+    const note = ctx.container.querySelector('[data-dsh-pet-renderer-fallback]')
+    expect(note?.textContent).toContain('live2d')
+    expect(note?.textContent).toContain('supported')
+    handle.dispose()
+    handle.dispose() // idempotent
+    expect(ctx.container.querySelector('[data-dsh-pet-renderer-fallback]')).toBeNull()
+  })
+})
+
+describe('contract constants', () => {
+  it('locks the renderer apiVersion', () => {
+    expect(PET_RENDERER_API_VERSION).toBe('x-org.linxin666.pet-center/v1alpha1')
+  })
+})

package/src/client/phase-stream.ts

@@ -0,0 +1,39 @@
+/**
+ * Phase stream — bridges the polled host snapshots onto the renderer
+ * contract's { get, subscribe } shape (pet-center M2 P4, issue #623). The
+ * existing poll loop pushes each snapshot's ActivityPhase; subscribers are
+ * dispatched on CHANGE only (phase transitions are sparse — done/failed hold
+ * a timed window before falling back to idle — and renderers like Live2D pay
+ * per transition, not per tick).
+ * @module @linxin666/dsh-pet/client/phase-stream
+ */
+
+import type { ActivityPhase } from '../state.ts'
+
+/** The renderer-facing phase stream. */
+export interface PhaseStream {
+  /** The latest pushed phase. */
+  get(): ActivityPhase
+  /** Subscribe to phase changes; returns the unsubscribe. */
+  subscribe(listener: (phase: ActivityPhase) => void): () => void
+  /** Feed a fresh snapshot phase; no-op when unchanged. */
+  push(phase: ActivityPhase): void
+}
+
+/** Create the stream (one per pet entry lifetime, owned by the plugin body). */
+export function createPhaseStream(initial: ActivityPhase = 'idle'): PhaseStream {
+  let current = initial
+  const listeners = new Set<(phase: ActivityPhase) => void>()
+  return {
+    get: () => current,
+    subscribe(listener) {
+      listeners.add(listener)
+      return () => { listeners.delete(listener) }
+    },
+    push(phase) {
+      if (phase === current) return
+      current = phase
+      for (const listener of [...listeners]) listener(phase)
+    },
+  }
+}

package/src/client/renderers/PetRendererSwitch.test.tsx

@@ -0,0 +1,66 @@
+// @vitest-environment jsdom
+/**
+ * PetRendererSwitch — the client dispatch seam (pet-center M2 P5, issue #623).
+ * sprite2d hands through to the sprite; an unservable renderer gets a clear
+ * diagnostic card instead of a blank pet.
+ */
+import { describe, expect, it } from 'vitest'
+import { cleanup, render } from '@testing-library/react'
+import { afterEach } from 'vitest'
+import { createElement } from 'react'
+import { PetRendererSwitch } from './PetRendererSwitch.tsx'
+import { defaultPetRendererRegistry } from './registry.ts'
+import type { PetRenderer } from '../../contracts/renderer.ts'
+import type { PetDefinition } from '../../registry.ts'
+import type { PropsLocale } from '@deepseek-ai/dsh-client-ui-slots'
+
+function definition(renderer?: string): PetDefinition {
+  return { id: 'x', displayName: 'X', description: '', renderer, cell: { width: 1, height: 1 }, columns: 8, rows: [], atlasRows: 9, tracks: {}, atlasUrl: '', manifestUrl: '' } as unknown as PetDefinition
+}
+
+const t = ((key: string, vars?: Record<string, string>) => key + (vars ? ' ' + JSON.stringify(vars) : '')) as unknown as PropsLocale<'pet'>['t']
+const noop = (): void => {}
+
+describe('PetRendererSwitch', () => {
+  afterEach(cleanup)
+  it('hands sprite2d definitions straight to the sprite', () => {
+    const { container } = render(createElement(PetRendererSwitch, { definition: definition('sprite2d'), phase: 'idle', onPet: noop, t }, createElement('span', { 'data-testid': 'sprite' })))
+    expect(container.querySelector('[data-testid="sprite"]')).toBeTruthy()
+    expect(document.querySelector('[data-dsh-pet-renderer-fallback]')).toBeNull()
+  })
+  it('treats a missing renderer as sprite2d (pre-M2 data)', () => {
+    const { container } = render(createElement(PetRendererSwitch, { definition: definition(undefined), phase: 'idle', onPet: noop, t }, createElement('span', { 'data-testid': 'sprite' })))
+    expect(container.querySelector('[data-testid="sprite"]')).toBeTruthy()
+  })
+  it('renders a diagnostic card for renderers this build cannot serve', () => {
+    const { container } = render(createElement(PetRendererSwitch, { definition: definition('live2d'), phase: 'idle', onPet: noop, t }, createElement('span', { 'data-testid': 'sprite' })))
+    expect(container.querySelector('[data-testid="sprite"]')).toBeNull()
+    const card = document.querySelector('[data-dsh-pet-renderer-fallback="live2d"]')
+    expect(card?.textContent).toContain('live2d')
+  })
+  it('injects the live2d visual into the sprite chrome once the renderer is registered (M3)', () => {
+    defaultPetRendererRegistry.register({
+      id: 'live2d',
+      apiVersion: 'test',
+      validateConfig: (config) => config,
+      mount: () => ({ dispose: () => {} }),
+    } as PetRenderer)
+    try {
+      const def = {
+        ...definition('live2d'),
+        live2d: { modelUrl: '/pet/x/x.model3.json', modelPath: 'x.model3.json', motions: { idle: 'Idle' } },
+      } as PetDefinition
+      let captured: { visual?: unknown } | undefined
+      const Probe = (props: { visual?: unknown }): null => {
+        captured = props
+        return null
+      }
+      render(createElement(PetRendererSwitch, { definition: def, phase: 'idle', onPet: noop, t }, createElement(Probe)))
+      expect(captured).toBeDefined()
+      expect(captured!.visual).toBeTruthy()
+      expect(document.querySelector('[data-dsh-pet-renderer-fallback]')).toBeNull()
+    } finally {
+      defaultPetRendererRegistry.clear()
+    }
+  })
+})

package/src/client/renderers/PetRendererSwitch.tsx

@@ -0,0 +1,48 @@
+/**
+ * Renderer switch — the client dispatch seam of the pet center (issue #623,
+ * milestone M2 P5 / M3). The pet's manifest picks the renderer: sprite2d
+ * hands straight through to the sprite; live2d injects its visual INTO the
+ * sprite chrome (the dock, bubbles and panel belong to the pet center, not
+ * the renderer); a renderer this build cannot serve renders a clear
+ * diagnostic card instead of blanking.
+ * @module @linxin666/dsh-pet/client/renderers/PetRendererSwitch
+ */
+
+import { cloneElement, isValidElement, type ReactElement, type ReactNode } from 'react'
+import type { PropsLocale } from '@deepseek-ai/dsh-client-ui-slots'
+import type { PetDefinition } from '../../registry.ts'
+import type { ActivityPhase } from '../../state.ts'
+import type { PetSpriteProps } from '../PetSprite.tsx'
+import { defaultPetRendererRegistry } from './registry.ts'
+import { Live2dVisualMount } from './live2d/Live2dVisualMount.tsx'
+import type { NS } from '../locales.ts'
+
+/** Dispatch one pet definition to its renderer; unknown kinds get a card. */
+export function PetRendererSwitch(props: {
+  definition: PetDefinition
+  /** Current activity phase (fed to renderer visuals). */
+  phase: ActivityPhase
+  /** The chrome's pet interaction (affinity write-back owner). */
+  onPet: () => void
+  t: PropsLocale<typeof NS>['t']
+  children?: ReactNode
+}): ReactElement {
+  const renderer = props.definition.renderer ?? 'sprite2d'
+  if (renderer === 'sprite2d') return <>{props.children}</>
+  if (renderer === 'live2d' && defaultPetRendererRegistry.has('live2d') && isValidElement<PetSpriteProps>(props.children)) {
+    const visual = (
+      <Live2dVisualMount
+        definition={props.definition}
+        phase={props.phase}
+        onPet={props.onPet}
+        t={props.t}
+      />
+    )
+    return cloneElement(props.children, { visual })
+  }
+  return (
+    <span data-dsh-pet-renderer-fallback={renderer}>
+      {props.t('pet.renderer.unavailable', { renderer })}
+    </span>
+  )
+}

package/src/client/renderers/live2d/Live2dVisualMount.tsx

@@ -0,0 +1,98 @@
+/**
+ * Live2D visual mount (pet-center M3) — the React bridge between the pet
+ * center chrome and the imperative live2d renderer. The bridge owns the
+ * contract context (asset base, phase stream, interaction write-back,
+ * activation cleanups), feeds the polled phase into the stream, forwards
+ * sub-4px taps as hit-test coordinates, and renders the localized error
+ * card when the renderer reports a fatal boot failure.
+ * @module @linxin666/dsh-pet/client/renderers/live2d/Live2dVisualMount
+ */
+
+import { useEffect, useRef, useState, type ReactElement } from 'react'
+import type { PropsLocale } from '@deepseek-ai/dsh-client-ui-slots'
+import type { PetDefinition } from '../../../registry.ts'
+import type { ActivityPhase } from '../../../state.ts'
+import { createPhaseStream, type PhaseStream } from '../../phase-stream.ts'
+import type { PetRendererContext } from '../../../contracts/renderer.ts'
+import { defaultPetRendererRegistry } from '../registry.ts'
+import type { Live2dErrorCode, Live2dRendererHandle } from '../live2d.ts'
+import type { NS } from '../../locales.ts'
+
+/** Mount the live2d renderer as the sprite's visual (inside the chrome). */
+export function Live2dVisualMount(props: {
+  definition: PetDefinition
+  phase: ActivityPhase
+  onPet: () => void
+  t: PropsLocale<typeof NS>['t']
+}): ReactElement {
+  const containerRef = useRef<HTMLDivElement | null>(null)
+  const streamRef = useRef<PhaseStream | null>(null)
+  const handleRef = useRef<Live2dRendererHandle | null>(null)
+  const downRef = useRef<{ x: number; y: number } | null>(null)
+  const [error, setError] = useState<Live2dErrorCode | null>(null)
+
+  // One activation per pet definition: build the contract context and mount.
+  useEffect(() => {
+    const container = containerRef.current
+    const live2d = props.definition.live2d
+    if (container === null || live2d === undefined) return undefined
+    streamRef.current ??= createPhaseStream(props.phase)
+    const cleanups: (() => void)[] = []
+    const ctx: PetRendererContext = {
+      petId: props.definition.id,
+      assetBase: '/pet/' + encodeURIComponent(props.definition.id),
+      container,
+      phase: streamRef.current,
+      interact: props.onPet,
+      onCleanup: (fn) => { cleanups.push(fn) },
+    }
+    let handle: Live2dRendererHandle
+    try {
+      handle = defaultPetRendererRegistry.mount('live2d', ctx, live2d) as Live2dRendererHandle
+    } catch {
+      setError('load-failed')
+      return () => { for (const fn of cleanups.splice(0)) fn() }
+    }
+    handleRef.current = handle
+    handle.onError?.(setError)
+    return () => {
+      handleRef.current = null
+      for (const fn of cleanups.splice(0)) fn()
+      handle.dispose()
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps -- one activation per pet identity
+  }, [props.definition])
+
+  // Feed the polled phase into the activation's stream (change-only).
+  useEffect(() => {
+    streamRef.current?.push(props.phase)
+  }, [props.phase])
+
+  return (
+    <div
+      ref={containerRef}
+      data-dsh-pet-live2d={props.definition.id}
+      style={{ width: '100%', height: '100%' }}
+      onPointerDown={(e) => { downRef.current = { x: e.clientX, y: e.clientY } }}
+      onPointerUp={(e) => {
+        const down = downRef.current
+        downRef.current = null
+        if (down === null) return
+        // A moved pointer is a drag (the chrome owns it), not a tap.
+        if (Math.abs(e.clientX - down.x) > 4 || Math.abs(e.clientY - down.y) > 4) return
+        const rect = e.currentTarget.getBoundingClientRect()
+        handleRef.current?.tap(e.clientX - rect.left, e.clientY - rect.top)
+      }}
+    >
+      {error !== null && (
+        <span data-dsh-pet-live2d-error={error}>
+          {error === 'core-missing'
+            ? props.t('pet.live2d.core-missing')
+            : error === 'vendor-missing'
+              ? props.t('pet.live2d.vendor-missing')
+              : props.t('pet.live2d.load-failed')}
+        </span>
+      )}
+    </div>
+  )
+}

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

@@ -0,0 +1,61 @@
+// @vitest-environment jsdom
+/**
+ * Live2D runtime loader tests (pet-center M3) — globals short-circuit, probe
+ * injection success/failure, and the runtime-route URLs the host serves.
+ */
+import { afterEach, describe, expect, it } from 'vitest'
+import { ensureCubismCore, ensureLive2dVendor, resetLive2dRuntime, type Live2dVendor } from './runtime.ts'
+
+afterEach(() => {
+  resetLive2dRuntime()
+  delete window.Live2DCubismCore
+  delete window.__dshPetLive2d
+})
+
+describe('ensureCubismCore', () => {
+  it('short-circuits when the global already exists', async () => {
+    window.Live2DCubismCore = {}
+    await expect(ensureCubismCore({ inject: () => Promise.reject(new Error('must not inject')) })).resolves.toBe(true)
+  })
+  it('injects the runtime-route core URL and checks the global afterwards', async () => {
+    const seen: string[] = []
+    const ok = await ensureCubismCore({
+      inject: (src) => {
+        seen.push(src)
+        window.Live2DCubismCore = {}
+        return Promise.resolve()
+      },
+    })
+    expect(ok).toBe(true)
+    expect(seen).toEqual(['/api/pet/runtime/live2dcubismcore.min.js'])
+  })
+  it('resolves false when the user has not installed the core', async () => {
+    await expect(ensureCubismCore({ inject: () => Promise.reject(new Error('404')) })).resolves.toBe(false)
+    // Even a successful script load without the global means absence.
+    await expect(ensureCubismCore({ inject: () => Promise.resolve() })).resolves.toBe(false)
+  })
+})
+
+describe('ensureLive2dVendor', () => {
+  it('short-circuits on the existing global', async () => {
+    const vendor = { marker: true } as unknown as Live2dVendor
+    window.__dshPetLive2d = vendor
+    await expect(ensureLive2dVendor({ inject: () => Promise.reject(new Error('must not inject')) })).resolves.toBe(vendor)
+  })
+  it('injects the vendor URL and returns the global it sets', async () => {
+    const seen: string[] = []
+    const vendor = { marker: true } as unknown as Live2dVendor
+    const loaded = await ensureLive2dVendor({
+      inject: (src) => {
+        seen.push(src)
+        window.__dshPetLive2d = vendor
+        return Promise.resolve()
+      },
+    })
+    expect(loaded).toBe(vendor)
+    expect(seen).toEqual(['/api/pet/runtime/live2d-vendor.js'])
+  })
+  it('resolves undefined when the vendor file is unavailable', async () => {
+    await expect(ensureLive2dVendor({ inject: () => Promise.reject(new Error('404')) })).resolves.toBeUndefined()
+  })
+})

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

@@ -0,0 +1,119 @@
+/**
+ * Live2D runtime loading (pet-center M3) — the two scripts a live2d mount
+ * needs, fetched lazily through the plugin's own runtime route: the
+ * user-supplied Cubism Core (proprietary; the plugin never bundles or
+ * downloads it — issue #623 M1 §0) and the plugin-shipped MIT vendor bundle
+ * (pixi.js + untitled-pixi-live2d-engine). Each loads at most once per page;
+ * concurrent mounts share the in-flight promise, and a failure is cached as
+ * 'absent' so a broken install stops retrying the network every mount.
+ *
+ * The vendor surface below is the structural slice the renderer consumes;
+ * the real objects come from 'window.__dshPetLive2d' (lib/live2d-vendor.js),
+ * so this module never imports pixi — the client bundle stays lean.
+ * @module @linxin666/dsh-pet/client/renderers/live2d/runtime
+ */
+
+/** Runtime file URLs the host serves ('/api/pet/runtime/<name>', M3-2). */
+const CORE_URL = '/api/pet/runtime/live2dcubismcore.min.js'
+const VENDOR_URL = '/api/pet/runtime/live2d-vendor.js'
+
+/** The pixi Application slice the renderer uses. */
+export interface Live2dVendorApp {
+  canvas: HTMLCanvasElement
+  stage: { addChild(child: unknown): unknown }
+  renderer: { readonly width: number; readonly height: number }
+  init(options: Record<string, unknown>): Promise<void>
+  destroy(removeView?: boolean, options?: Record<string, unknown>): void
+}
+
+/** The Live2DModel slice the renderer uses. */
+export interface Live2dVendorModel {
+  anchor: { set(x: number, y?: number): void }
+  position: { set(x: number, y: number): void }
+  scale: { set(x: number, y?: number): void }
+  readonly width: number
+  readonly height: number
+  internalModel: {
+    settings: {
+      motions?: Record<string, unknown[]>
+      hitAreas?: readonly { Name?: string }[]
+    }
+  }
+  motion(group: string, index?: number): Promise<unknown>
+  expression(name?: string): unknown
+  hitTest(x: number, y: number): string[]
+  on(event: string, fn: () => void): unknown
+}
+
+/** The vendor bundle global (window.__dshPetLive2d). */
+export interface Live2dVendor {
+  Application: new () => Live2dVendorApp
+  extensions: { add(...items: unknown[]): void }
+  Live2DPlugin: unknown
+  configureCubismSDK(options: Record<string, unknown>): void
+  Live2DModel: { from(source: string, options?: Record<string, unknown>): Promise<Live2dVendorModel> }
+}
+
+declare global {
+  interface Window {
+    Live2DCubismCore?: unknown
+    __dshPetLive2d?: Live2dVendor
+  }
+}
+
+/** Injects one classic script tag; resolves on load, rejects on error. */
+type ScriptInjector = (src: string) => Promise<void>
+
+const defaultInjector: ScriptInjector = (src) => new Promise<void>((resolve, reject) => {
+  const tag = document.createElement('script')
+  tag.src = src
+  tag.onload = () => resolve()
+  tag.onerror = () => reject(new Error('script failed to load: ' + src))
+  document.head.appendChild(tag)
+})
+
+/** Test seam: swap the network for a stub injector. */
+export interface Live2dRuntimeProbe {
+  inject?: ScriptInjector
+}
+
+let corePromise: Promise<boolean> | undefined
+let vendorPromise: Promise<Live2dVendor | undefined> | undefined
+
+/**
+ * Ensure the Cubism Core global exists, injecting the runtime-route script
+ * once when absent. Resolves false when the user has not installed the core
+ * (a normal state — the renderer turns it into install guidance).
+ */
+export function ensureCubismCore(probe: Live2dRuntimeProbe = {}): Promise<boolean> {
+  if (typeof window !== 'undefined' && window.Live2DCubismCore !== undefined) return Promise.resolve(true)
+  if (probe.inject !== undefined) {
+    return probe.inject(CORE_URL)
+      .then(() => typeof window !== 'undefined' && window.Live2DCubismCore !== undefined)
+      .catch(() => false)
+  }
+  corePromise ??= defaultInjector(CORE_URL)
+    .then(() => typeof window !== 'undefined' && window.Live2DCubismCore !== undefined)
+    .catch(() => false)
+  return corePromise
+}
+
+/** Ensure the plugin vendor bundle global exists (same caching discipline). */
+export function ensureLive2dVendor(probe: Live2dRuntimeProbe = {}): Promise<Live2dVendor | undefined> {
+  if (typeof window !== 'undefined' && window.__dshPetLive2d !== undefined) return Promise.resolve(window.__dshPetLive2d)
+  if (probe.inject !== undefined) {
+    return probe.inject(VENDOR_URL)
+      .then(() => typeof window !== 'undefined' ? window.__dshPetLive2d : undefined)
+      .catch(() => undefined)
+  }
+  vendorPromise ??= defaultInjector(VENDOR_URL)
+    .then(() => typeof window !== 'undefined' ? window.__dshPetLive2d : undefined)
+    .catch(() => undefined)
+  return vendorPromise
+}
+
+/** Reset the cached script promises (tests). */
+export function resetLive2dRuntime(): void {
+  corePromise = undefined
+  vendorPromise = undefined
+}

package/src/client/renderers/live2d/vendor-entry.ts

@@ -0,0 +1,14 @@
+/**
+ * Live2D vendor bundle entry (pet-center M3) — builds pixi.js plus the
+ * untitled-pixi-live2d-engine Cubism stack into lib/live2d-vendor.js, an IIFE
+ * exposing 'window.__dshPetLive2d'. The sprite-only client bundle never pays
+ * for this stack: the live2d renderer lazy-loads the vendor file through the
+ * plugin's own runtime route, after the user-supplied Cubism Core script
+ * ('window.Live2DCubismCore') is already present.
+ *
+ * Redistribution: pixi.js and untitled-pixi-live2d-engine are MIT-licensed
+ * and may ship inside this plugin; the proprietary Cubism Core is NEVER
+ * bundled (issue #623, milestone M1 §0).
+ */
+export { Application, Point, extensions } from 'pixi.js'
+export { configureCubismSDK, Live2DModel, Live2DPlugin } from 'untitled-pixi-live2d-engine/cubism'