@linxin666/dsh-pet 0.2.4 → 0.2.6

package/src/client/renderers/live2d.ts

@@ -68,6 +68,43 @@ const TAP_GROUP = 'TapBody'
  * 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
 
@@ -105,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 ?? {}
@@ -143,46 +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)
+      // 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) {
@@ -195,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-card.module.css

@@ -354,6 +354,8 @@
 }
 
 .selectOption {
+  /* 弹层是 max-height 受限的 flex 列：选项必须保持自然行高，超出交给弹层滚动 */
+  flex-shrink: 0;
   border-radius: 6px;
   padding: 6px 10px;
   font-size: 13px;

package/src/image-dimensions.test.ts

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

package/src/image-dimensions.ts

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

package/src/index.ts

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

package/src/registry.test.ts

@@ -597,10 +597,26 @@ describe('voice packs (pet-center M4, issue #677)', () => {
   })
 })
 describe('status decorations (pet-center M5, #567)', () => {
-  function writeDecoration(dir: string, name: string, manifest: Record<string, unknown>, strip = 'whale-frames.png'): void {
+  /** A minimal valid PNG header (signature + IHDR) with the given size. */
+  function pngHeader(width: number, height: number): Buffer {
+    const buf = Buffer.alloc(26)
+    Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]).copy(buf, 0)
+    buf.writeUInt32BE(13, 8)      // IHDR chunk length
+    buf.write('IHDR', 12)         // chunk type
+    buf.writeUInt32BE(width, 16)  // width
+    buf.writeUInt32BE(height, 20) // height
+    return buf
+  }
+
+  /** A strip whose pixel geometry matches baseManifest() (64x48 cell, 4 cols). */
+  function matchingStrip(): Buffer {
+    return pngHeader(64 * 4, 48)
+  }
+
+  function writeDecoration(dir: string, name: string, manifest: Record<string, unknown>, strip: Buffer | string = 'whale-frames.png'): void {
     mkdirSync(join(dir, name), { recursive: true })
     writeFileSync(join(dir, name, 'decoration.json'), JSON.stringify(manifest), 'utf8')
-    writeFileSync(join(dir, name, strip), 'png', 'utf8')
+    writeFileSync(join(dir, name, manifest.entry as string), strip)
   }
 
   const baseManifest = () => ({
@@ -618,7 +634,7 @@ describe('status decorations (pet-center M5, #567)', () => {
     const root = tempDir()
     try {
       const assets = join(root, 'assets')
-      writeDecoration(join(assets, 'decorations'), 'whale', baseManifest())
+      writeDecoration(join(assets, 'decorations'), 'whale', baseManifest(), matchingStrip())
       const registry = loadPetRegistry({ packageRoot: root, petsDir: '', dshPetsDir: '' })
       const entry = registry.decorationById?.('whale')
       expect(entry).toBeDefined()
@@ -635,9 +651,9 @@ describe('status decorations (pet-center M5, #567)', () => {
   it('lets a user decoration override the built-in by id', () => {
     const root = tempDir()
     try {
-      writeDecoration(join(root, 'assets', 'decorations'), 'whale', baseManifest())
+      writeDecoration(join(root, 'assets', 'decorations'), 'whale', baseManifest(), matchingStrip())
       const dsh = join(root, 'dsh')
-      writeDecoration(join(dsh, 'decorations'), 'whale', { ...baseManifest(), displayName: '家用鲸鱼' })
+      writeDecoration(join(dsh, 'decorations'), 'whale', { ...baseManifest(), displayName: '家用鲸鱼' }, matchingStrip())
       const registry = loadPetRegistry({ packageRoot: root, petsDir: '', dshPetsDir: dsh })
       expect(registry.decorationById?.('whale')?.id).toBe('whale')
       expect(registry.warnings.some(w => w.includes('user decoration whale overrides'))).toBe(true)
@@ -687,4 +703,41 @@ describe('status decorations (pet-center M5, #567)', () => {
       rmSync(root, { recursive: true, force: true })
     }
   })
+
+  it('warns and keeps a decoration whose strip geometry mismatches the descriptor', () => {
+    const root = tempDir()
+    try {
+      // Declared 64x48 cell x 4 columns = 256x48; the file is only 128x48
+      // (2 frames worth) — the client would silently render half the frames.
+      const dir = join(root, 'assets', 'decorations', 'short')
+      mkdirSync(dir, { recursive: true })
+      writeFileSync(join(dir, 'decoration.json'), JSON.stringify(baseManifest()), 'utf8')
+      writeFileSync(join(dir, 'whale-frames.png'), pngHeader(128, 48))
+      const registry = loadPetRegistry({ packageRoot: root, petsDir: '', dshPetsDir: '' })
+      // Warn-and-keep: the entry still lists (mirroring the missing-strip
+      // discipline) and the warning names the mismatch.
+      expect(registry.decorationById?.('whale')).toBeDefined()
+      expect(registry.warnings.some(w => w.includes('does not match cell'))).toBe(true)
+    } finally {
+      rmSync(root, { recursive: true, force: true })
+    }
+  })
+
+  it('does not warn when a matching strip is undecodable (non-image bytes)', () => {
+    const root = tempDir()
+    try {
+      const dir = join(root, 'assets', 'decorations', 'opaque')
+      mkdirSync(dir, { recursive: true })
+      writeFileSync(join(dir, 'decoration.json'), JSON.stringify(baseManifest()), 'utf8')
+      // Unrecognized bytes: the header reader returns undefined, so the scan
+      // stays silent (cannot verify != mismatch). Only the missing-file check
+      // applies.
+      writeFileSync(join(dir, 'whale-frames.png'), Buffer.from('not-an-image'))
+      const registry = loadPetRegistry({ packageRoot: root, petsDir: '', dshPetsDir: '' })
+      expect(registry.decorationById?.('whale')).toBeDefined()
+      expect(registry.warnings.some(w => w.includes('does not match cell'))).toBe(false)
+    } finally {
+      rmSync(root, { recursive: true, force: true })
+    }
+  })
 })

package/src/registry.ts

@@ -27,7 +27,7 @@
  * @module @linxin666/dsh-pet/registry
  */
 
-import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs'
+import { closeSync, existsSync, openSync, readFileSync, readSync, readdirSync, statSync } from 'node:fs'
 import { homedir } from 'node:os'
 import { basename, dirname, isAbsolute, join, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
@@ -35,6 +35,7 @@ import type { ActivityPhase, PetAnimation } from './state.ts'
 import { normalizePetRemarks, type PetRemarks, type PetRemarksManifest } from './remarks.ts'
 import { mergeVoicePacks, normalizeVoicePack, type PetPanelView, type VoicePack } from './voice-pack.ts'
 import { parseDecorationManifest } from './decoration.ts'
+import { imageDimensions } from './image-dimensions.ts'
 import { PET_DECORATION_API_VERSION, type DecorationView } from './contracts/status-decoration.ts'
 import { dshHome } from './dsh-home.ts'
 import { parsePetManifest, type PetManifestLive2d, type PetManifestV2, type PetRendererKind } from './manifest-v2.ts'
@@ -687,6 +688,27 @@ function loadVoicePackFile(
 /** Decoration asset URL prefix (served by the decoration route, M5). */
 export const DECORATION_ASSET_PREFIX = '/api/pet/decoration'
 
+/** Read the pixel dimensions of a decoration strip (PNG/WebP), if decodable. */
+function readImageDimensions(file: string): { width: number; height: number } | undefined {
+  let header: Buffer
+  try {
+    // Only the header is needed for dimensions; cap the read so a huge or
+    // corrupt strip cannot balloon memory during the registry scan.
+    const fd = openSync(file, 'r')
+    try {
+      header = Buffer.alloc(64)
+      const read = readSync(fd, header, 0, header.length, 0)
+      if (read < 0) return undefined
+      header = header.subarray(0, read)
+    } finally {
+      closeSync(fd)
+    }
+  } catch {
+    return undefined
+  }
+  return imageDimensions(header)
+}
+
 /**
  * Scan one directory of decoration folders ('decoration.json' + strip).
  * Later scans override earlier ones on id collision; a bad descriptor warns
@@ -730,6 +752,23 @@ function scanDecorationDir(dir: string, options: { warnings?: string[]; diagnost
       const message = 'decoration ' + manifest.id + ': strip file missing: ' + manifest.entry
       options.warnings?.push(message)
       options.diagnostics?.push({ level: 'warning', source: entryDir, message })
+    } else {
+      // Geometry check: the client renders the strip as a single row of
+      // 'columns' frames (background-position advances by frame width only),
+      // so the strip must be exactly cell.width * columns wide and cell.height
+      // tall. A mismatched strip silently shows the wrong/partial frames —
+      // warn-and-keep, mirroring the missing-strip discipline (never throw).
+      const actual = readImageDimensions(join(entryDir, manifest.entry))
+      if (actual !== undefined) {
+        const expectedWidth = manifest.cell.width * manifest.columns
+        if (actual.width !== expectedWidth || actual.height !== manifest.cell.height) {
+          const message = 'decoration ' + manifest.id + ': strip ' + actual.width + 'x' + actual.height
+            + ' does not match cell ' + manifest.cell.width + 'x' + manifest.cell.height + ' x ' + manifest.columns
+            + ' columns (expected ' + expectedWidth + 'x' + manifest.cell.height + '); frames will render wrong'
+          options.warnings?.push(message)
+          options.diagnostics?.push({ level: 'warning', source: entryDir, message })
+        }
+      }
     }
     entries.push({
       apiVersion: PET_DECORATION_API_VERSION,