@linxin666/dsh-pet 0.3.4 → 0.3.6

package/src/client/PetSprite.test.tsx

@@ -176,6 +176,24 @@ describe('PetSprite hide control (#1126)', () => {
   })
 })
 
+describe('PetSprite affinity rank localization (#1226)', () => {
+  it('localizes the rank name in the hover panel when document language is en', () => {
+    document.documentElement.lang = 'en'
+    try {
+      renderPet({
+        snapshot: {
+          ...snapshot,
+          affinity: { ...snapshot.affinity, rank: '幼鲸' },
+        },
+      })
+      fireEvent.pointerOver(screen.getByRole('button', { name: '鲸鱼娘' }))
+      expect(screen.getByText('Affinity Baby Whale')).toBeTruthy()
+    } finally {
+      document.documentElement.lang = 'zh'
+    }
+  })
+})
+
 describe('PetSprite rename input', () => {
   it('submits the draft on Enter outside composition', () => {
     const { onRename } = renderPet()
@@ -424,27 +442,18 @@ describe('PetSprite status bubble', () => {
     expect(screen.queryByText('正在使用 grep')).not.toBeNull()
   })
 
-  it('lets the inner whisper take over the status bubble', () => {
-    renderPet({ snapshot: { ...workingSnapshot, whisper: '哼哧哼哧，大脑转得飞快～' } })
-    // The whisper speaks THROUGH the bubble: it replaces (not accompanies)
-    // the status copy, so the pet never shows two bubbles at once.
-    expect(screen.queryByText('哼哧哼哧，大脑转得飞快～')).not.toBeNull()
-    expect(screen.queryByText('正在思考')).toBeNull()
-  })
-
-  it('lets the whisper take over the display session bubble in the stack', () => {
+  it('lets a session whisper take over its own bubble while others stay collapsed', () => {
     const { onOpenSession } = renderPet({
       snapshot: {
         ...workingSnapshot,
-        whisper: '我在这儿陪着你呢，别急别急',
         sessions: [
-          { sessionId: 's-a', animation: 'running', phase: 'thinking', bubble: '正在思考' },
+          { sessionId: 's-a', animation: 'running', phase: 'thinking', bubble: '正在思考', whisper: '我在这儿陪着你呢，别急别急' },
           { sessionId: 's-b', animation: 'running-right', phase: 'tool', bubble: '正在使用 grep' },
         ],
       },
     })
-    // The primary bubble (the display session) speaks the whisper instead
-    // of its status copy; the collapsed extra session hides behind the badge.
+    // The lead session's bubble speaks ITS whisper instead of its status
+    // copy; the collapsed extra session hides behind the badge.
     expect(screen.queryByText('我在这儿陪着你呢，别急别急')).not.toBeNull()
     expect(screen.queryByText('正在思考')).toBeNull()
     expect(screen.queryByText('正在使用 grep')).toBeNull()
@@ -456,9 +465,28 @@ describe('PetSprite status bubble', () => {
     expect(onOpenSession).toHaveBeenCalledWith('s-a')
   })
 
+  it('renders each session whisper on its own expanded bubble', () => {
+    renderPet({
+      snapshot: {
+        ...workingSnapshot,
+        sessions: [
+          { sessionId: 's-a', animation: 'running', phase: 'thinking', bubble: '正在思考', whisper: 'A 的碎碎念' },
+          { sessionId: 's-b', animation: 'running-right', phase: 'tool', bubble: '正在使用 grep', whisper: 'B 的碎碎念' },
+        ],
+      },
+    })
+    fireEvent.pointerOver(screen.getByText('A 的碎碎念').closest('div')!)
+    expect(screen.queryByText('A 的碎碎念')).not.toBeNull()
+    expect(screen.queryByText('B 的碎碎念')).not.toBeNull()
+    expect(screen.queryByText('正在思考')).toBeNull()
+  })
+
   it('lets transient interaction feedback take over the whisper too', () => {
     renderPet({
-      snapshot: { ...workingSnapshot, whisper: '哼哧哼哧，大脑转得飞快～' },
+      snapshot: {
+        ...workingSnapshot,
+        sessions: [{ sessionId: 's-a', animation: 'running', phase: 'thinking', bubble: '正在思考', whisper: '哼哧哼哧，大脑转得飞快～' }],
+      },
       feedback: { text: '摸摸成功', kind: 'pet', at: 1 },
     })
     expect(screen.queryByText('摸摸成功')).not.toBeNull()
@@ -754,7 +782,14 @@ describe('PetSprite status decoration (pet-center M5, #567)', () => {
   })
 
   it('yields the bubble to the whisper (voice moment hides the ornament)', () => {
-    renderPet({ snapshot: { ...snapshot, phase: 'thinking', whisper: '冲了冲了', decoration } })
+    renderPet({
+      snapshot: {
+        ...snapshot,
+        phase: 'thinking',
+        decoration,
+        sessions: [{ sessionId: 's-a', animation: 'running', phase: 'thinking', bubble: '正在思考', whisper: '冲了冲了' }],
+      },
+    })
     expect(ornament()).toBeNull()
     expect(document.body.textContent).toContain('冲了冲了')
   })

package/src/client/PetSprite.tsx

@@ -432,14 +432,14 @@ export function PetSprite(props: PetSpriteProps): ReactPortal {
   const statusBubble = feedback === null && sessionBubbles.length === 0
     ? snapshot?.bubble
     : undefined
-  // The display session's inner whisper (碎碎念) — short inner-voice copy
-  // woken by the model's output. Instead of a second bubble of its own, a
-  // fresh whisper takes over the display session's bubble (the stack top, or
-  // the single status bubble) and re-tints it, so the pet never wears two
-  // voices at once. Interaction feedback takes over the whole bubble area
-  // while it plays, so whispers yield to it like status copy.
-  const whisper = feedback === null ? snapshot?.whisper : undefined
-  const bubblePresent = feedback !== null || sessionBubbles.length > 0 || statusBubble !== undefined || whisper !== undefined
+  // Each session's inner whisper (碎碎念) rides its own bubble — short
+  // inner-voice copy woken by that session's activity, never the model's or
+  // another session's. Instead of a second bubble of its own, a fresh
+  // whisper takes over its session's bubble and re-tints it, so the pet
+  // never wears two voices at once. Interaction feedback takes over the
+  // whole bubble area while it plays, so whispers yield to it like status
+  // copy.
+  const bubblePresent = feedback !== null || sessionBubbles.length > 0 || statusBubble !== undefined
   const displayName = snapshot?.name ?? definition.displayName
   // The host-served status decoration (M5, #567); absent = text-only bubbles.
   const decoration = snapshot?.decoration
@@ -549,7 +549,7 @@ export function PetSprite(props: PetSpriteProps): ReactPortal {
           {feedback.text}
         </div>
       )}
-      {feedback === null && (sessionBubbles.length > 0 || statusBubble !== undefined || whisper !== undefined) && (
+      {feedback === null && (sessionBubbles.length > 0 || statusBubble !== undefined) && (
         <div
           ref={bubbleRef}
           className={styles.bubbleStack}
@@ -557,15 +557,14 @@ export function PetSprite(props: PetSpriteProps): ReactPortal {
           onPointerLeave={() => setStackPeek(false)}
         >
           {visibleSessions.map((session, index) => {
-            // The whisper rides the display session's bubble — the stack's
-            // primary entry (DOM-first, rendered bottom-most by the reversed
-            // column so it stays glued to the sprite when extras open above).
-            // The key swap restarts the entrance animation so the mood change
-            // reads as the bubble re-speaking.
-            const speaksWhisper = index === 0 && whisper !== undefined
+            // A session's whisper rides ITS OWN bubble (the stack lead when
+            // the current session has one, any bubble when the stack is
+            // expanded). The key swap restarts the entrance animation so the
+            // mood change reads as the bubble re-speaking.
+            const speaksWhisper = session.whisper !== undefined
             const bubble = (
               <button
-                key={speaksWhisper ? 'whisper:' + whisper : session.sessionId}
+                key={speaksWhisper ? 'whisper:' + session.whisper : session.sessionId}
                 type="button"
                 className={clsx(
                   styles.bubble,
@@ -579,7 +578,7 @@ export function PetSprite(props: PetSpriteProps): ReactPortal {
                 {index === 0 && !speaksWhisper && decoration !== undefined && (
                   <StatusOrnament decoration={decoration} phase={phase} />
                 )}
-                {speaksWhisper ? whisper : session.bubble}
+                {session.whisper ?? session.bubble}
               </button>
             )
             // The primary bubble carries the '+N' badge while other sessions
@@ -608,19 +607,17 @@ export function PetSprite(props: PetSpriteProps): ReactPortal {
               </span>
             )
           })}
-          {sessionBubbles.length === 0 && (statusBubble !== undefined || whisper !== undefined) && (
-            // The key swap (status copy <-> whisper) restarts the entrance
-            // animation on every mood change.
+          {sessionBubbles.length === 0 && statusBubble !== undefined && (
             <div
-              key={whisper === undefined ? 'status' : 'whisper:' + whisper}
-              className={clsx(styles.bubble, styles.bubbleStatus, whisper !== undefined && styles.bubbleWhisper)}
+              key="status"
+              className={clsx(styles.bubble, styles.bubbleStatus)}
               role="status"
               aria-live="polite"
             >
-              {whisper === undefined && decoration !== undefined && (
+              {decoration !== undefined && (
                 <StatusOrnament decoration={decoration} phase={phase} />
               )}
-              {whisper ?? statusBubble}
+              {statusBubble}
             </div>
           )}
         </div>
@@ -688,7 +685,15 @@ export function PetSprite(props: PetSpriteProps): ReactPortal {
             <>
               <div className={styles.rankRow}>
                 <span className={styles.nameCell}>{displayName}</span>
-                <span className={styles.statRank}>{panelStat('rank', 'pet.rank', { rank: snapshot?.affinity.rank ?? '?' })}</span>
+                <span className={styles.statRank}>
+                  {(() => {
+                    const rawRank = snapshot?.affinity.rank ?? '?'
+                    const rankKey = `pet.rank.name.${rawRank}`
+                    const localized = props.t(rankKey as any)
+                    const rankName = localized !== rankKey ? localized : rawRank
+                    return panelStat('rank', 'pet.rank', { rank: rankName })
+                  })()}
+                </span>
               </div>
               <div className={styles.rankRow}>
                 <span className={styles.statTreats}>{panelStat('treats', 'pet.treats', { n: snapshot?.treats.stocked ?? 0 })}</span>

package/src/client/index.test.tsx

@@ -110,7 +110,16 @@ function fakeContext(): FakeClientLifecycle {
       },
       register: () => () => {},
     },
-    sessions: undefined,
+    sessions: {
+      list: {
+        getSnapshot: () => ({ current: undefined, byId: {} }),
+        subscribe: (listener: () => void) => {
+          const set = new Set<() => void>([listener])
+          return () => { set.delete(listener) }
+        },
+      },
+      open: () => {},
+    },
   } as unknown as ClientContext
   let disposed = false
   const lifecycle: FakeClientLifecycle = {

package/src/client/index.ts

@@ -36,7 +36,8 @@ import { reportDailyHeartbeat } from './telemetry.ts'
 
 /** The host pet API as the browser sees it (same-origin JSON endpoints). */
 interface PetHttpApi {
-  state(): Promise<PetStateView>
+  /** Poll the host snapshot; the GUI's current session id rides the query. */
+  state(currentSessionId?: string): Promise<PetStateView>
   pets(): Promise<PetDefinition[]>
   interact(kind: PetInteraction): Promise<PetInteractResult>
   setVisible(visible: boolean): Promise<{ ok: true; display: PetDisplayConfig }>
@@ -66,7 +67,8 @@ async function petFetch<T>(path: string, body?: unknown): Promise<T> {
 
 /** The live host API instance (always defined; failures surface per call). */
 const petApi: PetHttpApi = {
-  state: () => petFetch('/api/pet/state'),
+  state: (currentSessionId) => petFetch('/api/pet/state'
+    + (currentSessionId === undefined ? '' : '?current=' + encodeURIComponent(currentSessionId))),
   pets: () => petFetch('/api/pet/pets'),
   interact: (kind) => petFetch('/api/pet/interact', { kind }),
   setVisible: (visible) => petFetch('/api/pet/set-visible', { visible }),
@@ -197,6 +199,20 @@ export function apply(ctx: ClientContext): void {
       const setState = petStore.actions.setState
       const setFeedback = petStore.actions.setFeedback
 
+      // Clicking a session bubble jumps the GUI to that session; the same
+      // sessions face reports which session the user is currently on, so the
+      // host can lead the bubble stack with it. A bubble can outlive its
+      // disposed session by one poll tick, and the sessions service fails
+      // loud on unknown ids, so consult the live list first. The pet's type
+      // program also loads the host-side dsh-session package through the
+      // service types, whose Context merge declares a different 'sessions'
+      // face; pin the browser runtime's outward face here.
+      const sessions = ctx.sessions as unknown as ISessions
+      const currentSessionId = (): string | undefined => {
+        const current = sessions.list.getSnapshot().current
+        return current === undefined ? undefined : String(current)
+      }
+
       // The registry list is fetched lazily with retries baked into the poll
       // cycle: until it lands, the dock entry renders nothing and every 2s
       // tick tries again. After it lands, one list feeds both the sprite and
@@ -218,7 +234,7 @@ export function apply(ctx: ClientContext): void {
         }
         const seq = stateSeq + 1
         stateSeq = seq
-        petApi.state().then((snapshot) => {
+        petApi.state(currentSessionId()).then((snapshot) => {
           if (seq !== stateSeq) return
           setSnapshot(snapshot)
         }, () => {
@@ -261,13 +277,16 @@ export function apply(ctx: ClientContext): void {
         }
       }, 'pet: poll')
 
-      // Clicking a session bubble jumps the GUI to that session. A bubble
-      // can outlive its disposed session by one poll tick, and the sessions
-      // service fails loud on unknown ids, so consult the live list first.
-      // The pet's type program also loads the host-side dsh-session package
-      // through the service types, whose Context merge declares a different
-      // 'sessions' face; pin the browser runtime's outward face here.
-      const sessions = ctx.sessions as unknown as ISessions
+      // A current-session switch should re-order the bubble stack right away,
+      // not on the next 2s tick. Poll only while the tab is visible, as the
+      // poll loop itself does.
+      const disposeSessionWatch = ctx.effect(() => {
+        const unsubscribe = sessions.list.subscribe(() => {
+          if (document.visibilityState === 'visible') pollNow()
+        })
+        return unsubscribe
+      }, 'pet: current-session watch')
+
       const openSession = (sessionId: string): void => {
         const list = sessions.list.getSnapshot()
         if (list.byId[sessionId as SessionId] === undefined) return

package/src/client/locales.ts

@@ -15,6 +15,15 @@ export const zh = {
   'pet.namePlaceholder': '输入新名字',
   'pet.summon': '召唤{name}',
   'pet.rank': '亲密度 {rank}',
+  'pet.rank.name.幼鲸': '幼鲸',
+  'pet.rank.name.伙伴': '伙伴',
+  'pet.rank.name.挚友': '挚友',
+  'pet.rank.name.深海羁绊': '深海羁绊',
+  'pet.rank.name.心有灵犀': '心有灵犀',
+  'pet.rank.name.传说羁绊': '传说羁绊',
+  'pet.rank.name.神话羁绊': '神话羁绊',
+  'pet.rank.name.永恒之契': '永恒之契',
+  'pet.rank.name.鲸生共渡': '鲸生共渡',
   'pet.points': '{points} 点',
   'pet.treats': '小鱼干 ×{n}',
   'pet.state.loading': '宠物正在赶来…',
@@ -88,6 +97,15 @@ export const en = {
   'pet.namePlaceholder': 'Enter a new name',
   'pet.summon': 'Summon {name}',
   'pet.rank': 'Affinity {rank}',
+  'pet.rank.name.幼鲸': 'Baby Whale',
+  'pet.rank.name.伙伴': 'Companion',
+  'pet.rank.name.挚友': 'Close Friend',
+  'pet.rank.name.深海羁绊': 'Deep Sea Bond',
+  'pet.rank.name.心有灵犀': 'Kindred Spirit',
+  'pet.rank.name.传说羁绊': 'Legendary Bond',
+  'pet.rank.name.神话羁绊': 'Mythic Bond',
+  'pet.rank.name.永恒之契': 'Eternal Covenant',
+  'pet.rank.name.鲸生共渡': 'Lifelong Companion',
   'pet.points': '{points} pts',
   'pet.treats': 'Treats ×{n}',
   'pet.state.loading': 'The pet is on its way…',

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

@@ -135,3 +135,104 @@ describe('frames2dRenderer', () => {
     expect(container.querySelector('img')).toBeNull()
   })
 })
+
+describe('frames2dRenderer canvas bitmap path', () => {
+  // The canvas branch needs createImageBitmap + fetch + a real 2D context;
+  // jsdom has none of them, so each test installs fakes and restores after.
+  const flush = async (): Promise<void> => {
+    await Promise.resolve()
+    await Promise.resolve()
+    await Promise.resolve()
+  }
+
+  let draws = 0
+  const bitmaps: { width: number; height: number; close: ReturnType<typeof vi.fn> }[] = []
+
+  beforeEach(() => {
+    vi.useFakeTimers()
+    document.body.innerHTML = ''
+    draws = 0
+    bitmaps.length = 0
+    vi.stubGlobal('fetch', vi.fn(async () => ({ ok: true, blob: async () => ({}) })))
+    vi.stubGlobal('createImageBitmap', vi.fn(async () => {
+      const bmp = { width: 32, height: 32, close: vi.fn() }
+      bitmaps.push(bmp)
+      return bmp
+    }))
+    ;(HTMLCanvasElement.prototype as unknown as { getContext: unknown }).getContext = () => ({
+      clearRect: () => {},
+      drawImage: () => {
+        draws += 1
+      },
+    })
+  })
+
+  afterEach(() => {
+    vi.unstubAllGlobals()
+    Reflect.deleteProperty(HTMLCanvasElement.prototype as unknown as Record<string, unknown>, 'getContext')
+    vi.useRealTimers()
+  })
+
+  function canvasSetup() {
+    const container = document.createElement('div')
+    document.body.appendChild(container)
+    const ctx: PetRendererContext = {
+      petId: 'miku',
+      assetBase: '/pet/miku',
+      container,
+      phase: createPhaseStream('idle'),
+      interact: () => {},
+      onCleanup: () => {},
+    }
+    return { ctx, container }
+  }
+
+  it('mounts a canvas instead of an img and paints advanced frames via drawImage', async () => {
+    const { ctx, container } = canvasSetup()
+    const handle = frames2dRenderer.mount(ctx, frames2dRenderer.validateConfig(CONFIG)) as Frames2dRendererHandle
+    expect(container.querySelector('canvas')).not.toBeNull()
+    expect(container.querySelector('img')).toBeNull()
+    await flush()
+    // Warm pass decoded every configured frame exactly once; the first frame
+    // of the idle track painted during mount.
+    expect(bitmaps.length).toBe(6)
+    const paintsAtMount = draws
+    expect(paintsAtMount).toBeGreaterThanOrEqual(1)
+    vi.advanceTimersByTime(100)
+    await flush()
+    expect(draws).toBeGreaterThan(paintsAtMount)
+    handle.dispose()
+  })
+
+  it('sizes the backing store from decoded dimensions and releases bitmaps on dispose', async () => {
+    const { ctx, container } = canvasSetup()
+    const handle = frames2dRenderer.mount(ctx, frames2dRenderer.validateConfig(CONFIG)) as Frames2dRendererHandle
+    await flush()
+    const canvas = container.querySelector('canvas')!
+    expect(canvas.width).toBe(32)
+    expect(canvas.height).toBe(32)
+    handle.dispose()
+    await flush()
+    for (const bmp of bitmaps) expect(bmp.close).toHaveBeenCalled()
+  })
+
+  it('keeps painting through a phase switch without touching the DOM tree', async () => {
+    const { container } = canvasSetup()
+    const stream = createPhaseStream('idle')
+    const ctx: PetRendererContext = {
+      petId: 'miku', assetBase: '/pet/miku', container, phase: stream, interact: () => {}, onCleanup: () => {},
+    }
+    const handle = frames2dRenderer.mount(ctx, frames2dRenderer.validateConfig(CONFIG)) as Frames2dRendererHandle
+    await flush()
+    const nodesBefore = container.querySelectorAll('*').length
+    stream.push('thinking' as ActivityPhase)
+    expect(handle.currentTrack()).toBe('work')
+    await flush()
+    vi.advanceTimersByTime(100)
+    await flush()
+    // Steady-state playback is DOM-mutation-free: no element added or removed.
+    expect(container.querySelectorAll('*').length).toBe(nodesBefore)
+    expect(draws).toBeGreaterThanOrEqual(3)
+    handle.dispose()
+  })
+})

package/src/client/renderers/frames2d.ts

@@ -8,6 +8,18 @@
  * phase-mapped track. Rendering never throws: a broken track list degrades
  * to the first decodable frame, and the 1.2 s stall watchdog re-kicks the
  * playback chain after timer throttling.
+ *
+ * Frame presentation has two modes picked once at mount by capability
+ * probing:
+ * - Canvas bitmap buffer (default where createImageBitmap/fetch/2D context
+ *   exist): every frame is decoded exactly once into an ImageBitmap during
+ *   the warm pass and drawn onto one <canvas> - steady-state playback issues
+ *   zero DOM mutations and zero re-decodes (measured hotspot: swapping
+ *   <img>.src per frame drove image decode + invalidation every tick).
+ * - Classic <img> fallback (jsdom/tests or missing APIs): identical to the
+ *   historical behavior - cache-warm Image elements plus guarded src swaps,
+ *   so environments without modern decoding keep working unchanged.
+ *
  * @module @linxin666/dsh-pet/client/renderers/frames2d
  */
 
@@ -69,6 +81,12 @@ function validateFrames2dConfig(config: unknown): PetFrames2dConfig {
   return { tracks, phases: phases as PetFrames2dConfig['phases'] }
 }
 
+interface DecodedFrame {
+  source: ImageBitmap | HTMLImageElement
+  width: number
+  height: number
+}
+
 export const frames2dRenderer: PetRenderer<PetFrames2dConfig> = {
   id: 'frames2d',
   apiVersion: PET_RENDERER_API_VERSION,
@@ -79,23 +97,78 @@ export const frames2dRenderer: PetRenderer<PetFrames2dConfig> = {
       && typeof window.matchMedia === 'function'
       && window.matchMedia('(prefers-reduced-motion: reduce)').matches
 
-    const img = document.createElement('img')
-    img.dataset.dshPetFrames2d = ctx.petId
-    img.alt = ''
-    img.draggable = false
-    img.style.width = '100%'
-    img.style.height = '100%'
-    img.style.objectFit = 'contain'
-    img.style.pointerEvents = 'none'
-    ctx.container.appendChild(img)
-
-    // Warm the browser cache for every frame up front (same-origin, small
-    // webp files); playback itself swaps img.src without React state.
-    for (const track of Object.values(config.tracks)) {
-      for (const url of track.frames) {
-        const pre = new Image()
-        pre.src = url
+    // Capability probe: the canvas path needs decode-to-bitmap, same-origin
+    // fetch, and a real 2D context (jsdom returns null and falls back below).
+    let canvas: HTMLCanvasElement | null = null
+    let context2d: CanvasRenderingContext2D | null = null
+    let img: HTMLImageElement | null = null
+    try {
+      if (typeof createImageBitmap === 'function' && typeof fetch === 'function') {
+        const probe = document.createElement('canvas')
+        const c2d = probe.getContext('2d')
+        if (c2d !== null) {
+          canvas = probe
+          context2d = c2d
+        }
       }
+    } catch {
+      canvas = null
+      context2d = null
+    }
+
+    if (canvas !== null && context2d !== null) {
+      canvas.dataset.dshPetFrames2d = ctx.petId
+      canvas.draggable = false
+      canvas.style.width = '100%'
+      canvas.style.height = '100%'
+      canvas.style.objectFit = 'contain'
+      canvas.style.pointerEvents = 'none'
+      ctx.container.appendChild(canvas)
+    } else {
+      img = document.createElement('img')
+      img.dataset.dshPetFrames2d = ctx.petId
+      img.alt = ''
+      img.draggable = false
+      img.style.width = '100%'
+      img.style.height = '100%'
+      img.style.objectFit = 'contain'
+      img.style.pointerEvents = 'none'
+      ctx.container.appendChild(img)
+    }
+
+    // Decode cache: one concurrent decode per URL, memoized forever (frames
+    // are tiny same-origin webp files; failures resolve undefined and keep
+    // the last painted frame instead of breaking playback).
+    const decoding = new Map<string, Promise<DecodedFrame | undefined>>()
+    const decodedAll: Promise<void>[] = []
+    const loadFrame = (url: string): Promise<DecodedFrame | undefined> => {
+      const cached = decoding.get(url)
+      if (cached !== undefined) return cached
+      const job: Promise<DecodedFrame | undefined> = (async () => {
+        try {
+          const response = await fetch(url)
+          if (!response.ok) throw new Error('http ' + response.status)
+          const bitmap = await createImageBitmap(await response.blob())
+          return { source: bitmap, width: bitmap.width, height: bitmap.height }
+        } catch {
+          // Fail-open: classic Image decode keeps non-modern runtimes alive.
+          return await new Promise<DecodedFrame | undefined>((resolve) => {
+            try {
+              const pre = new Image()
+              pre.onload = (): void => {
+                resolve(pre.naturalWidth > 0 ? { source: pre, width: pre.naturalWidth, height: pre.naturalHeight } : undefined)
+              }
+              pre.onerror = (): void => resolve(undefined)
+              pre.src = url
+            } catch {
+              resolve(undefined)
+            }
+          })
+        }
+      })()
+      decoding.set(url, job)
+      decodedAll.push(job.then(() => undefined, () => undefined))
+      return job
     }
 
     let disposed = false
@@ -105,16 +178,42 @@ export const frames2dRenderer: PetRenderer<PetFrames2dConfig> = {
     let frameIndex = 0
     let lastAdvance = Date.now()
     let override: string | undefined
+    let drawToken = 0
+    let lastDrawnUrl: string | undefined
 
     const trackForPhase = (phase: ActivityPhase): string => {
       const mapped = config.phases[phase]
       return mapped !== undefined && config.tracks[mapped] !== undefined ? mapped : config.phases.idle
     }
 
+    /** Canvas path: paints the newest requested frame; stale draws drop out. */
+    const paintCanvas = (url: string): void => {
+      if (context2d === null || canvas === null) return
+      const myToken = ++drawToken
+      void loadFrame(url).then((frame) => {
+        if (disposed || frame === undefined || myToken !== drawToken) return
+        if (lastDrawnUrl === url) return
+        lastDrawnUrl = url
+        // Resizing clears the canvas, so size only when it actually differs.
+        if (canvas.width !== frame.width || canvas.height !== frame.height) {
+          canvas.width = frame.width
+          canvas.height = frame.height
+        } else {
+          context2d.clearRect(0, 0, canvas.width, canvas.height)
+        }
+        context2d.drawImage(frame.source as CanvasImageSource, 0, 0)
+      }).catch(() => { /* keep last frame */ })
+    }
+
     const show = (trackId: string, index: number): void => {
       const def = config.tracks[trackId]
       const url = def?.frames[index]
-      if (url !== undefined && img.getAttribute('src') !== url) img.src = url
+      if (url === undefined) return
+      if (img !== null) {
+        if (img.getAttribute('src') !== url) img.src = url
+        return
+      }
+      paintCanvas(url)
     }
 
     const schedule = (ms: number): void => {
@@ -180,6 +279,13 @@ export const frames2dRenderer: PetRenderer<PetFrames2dConfig> = {
       }, WATCHDOG_MS)
     }
 
+    // Warm pass: decode every frame up front (tiny same-origin webp files)
+    // so loops and phase switches never wait on a first decode - same intent
+    // as the historical Image-cache warm loop, now feeding the decode cache.
+    for (const warmTrack of Object.values(config.tracks)) {
+      for (const warmUrl of warmTrack.frames) void loadFrame(warmUrl)
+    }
+
     play(track)
 
     let disposedOnce = false
@@ -190,7 +296,21 @@ export const frames2dRenderer: PetRenderer<PetFrames2dConfig> = {
       unsubscribe()
       if (timer !== undefined) clearTimeout(timer)
       if (watchdog !== undefined) clearInterval(watchdog)
-      img.remove()
+      // Release decoded bitmaps after pending decodes settle; close() is
+      // browser-only, so guard it for exotic hosts.
+      void Promise.allSettled(decodedAll).then(() => {
+        for (const job of decoding.values()) {
+          void job.then((frame) => {
+            try {
+              const maybeClose = (frame?.source as { close?: () => void } | undefined)?.close
+              if (typeof maybeClose === 'function' && frame !== undefined) maybeClose.call(frame.source)
+            } catch { /* already released */ }
+          }).catch(() => { /* never rejects anyway */ })
+        }
+        decoding.clear()
+      })
+      canvas?.remove()
+      img?.remove()
     }
     ctx.onCleanup(dispose)