pi-simocracy 0.3.0 → 0.5.0

package/README.md

@@ -1,18 +1,28 @@
 # pi-simocracy
 
 Load a [Simocracy](https://simocracy.org) sim into your [`pi`](https://github.com/mariozechner/pi-coding-agent) chat — see its
-pixel-art sprite render in the terminal and chat with the agent **as that sim**.
+sprite render in the terminal and chat with the agent **as that sim**.
 
 ```
 /sim mr meow
 ```
 
 …fetches Mr Meow from Simocracy's ATProto indexer, renders his 32×32
-sprite as colored ANSI half-blocks directly in the chat, and pushes
-his constitution + speaking style into pi's system prompt so pi
+pixel-art sprite as colored ANSI half-blocks directly in the chat, and
+pushes his constitution + speaking style into pi's system prompt so pi
 roleplays as Mr Meow until you `/sim unload`.
 
-![Mr Meow loaded inline in pi](demo/sim-load.gif)
+<p align="center">
+  <img src="https://raw.githubusercontent.com/GainForest/pi-simocracy/main/demo/sim-load.gif" alt="Mr Meow (a pipoya pixel-art cat) loaded inline in pi's chat" width="760">
+</p>
+
+As of v0.4.0, codex pet sims (OpenAI hatch-pet skill output) render too —
+load **Einstein** with `/sim einstein` and the WebP atlas decodes, the
+idle frame crops, and the half-block ANSI render fires inline:
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/GainForest/pi-simocracy/main/demo/codex-pet-load.gif" alt="Einstein (a codex pet sim with a WebP petSheet) loaded inline in pi's chat" width="760">
+</p>
 
 ---
 
@@ -109,11 +119,37 @@ The same actions are exposed to pi as tools, so the model can drive them itself:
    - `org.simocracy.sim`     — display name + sprite + avatar blob refs
    - `org.simocracy.agents`  — short description + full constitution
    - `org.simocracy.style`   — speaking style / mannerisms
-4. **Render.** Fetch the sprite-sheet blob (128×128 PNG, 4×4 of 32×32
-   walking frames) via `com.atproto.sync.getBlob`, decode with `pngjs`,
-   crop the front-facing walk-1 frame, emit as 24-bit ANSI using the
-   upper-half-block character `▀` so each terminal cell paints two
-   pixels. Transparent regions show pi's background through.
+4. **Render.** Fetch the sprite blob via `com.atproto.sync.getBlob`,
+   decode it, crop the front-facing idle frame. Two render paths
+   depending on the sim's `spriteKind`:
+   - **`pipoya`** (legacy + default): 128×128 PNG, 4×4 of 32×32 walking
+     frames; decode with `pngjs`, take row 0 col 0 at native size.
+   - **`codexPet`** (OpenAI hatch-pet output): 1536×1872 atlas, 8×9 of
+     192×208 cells. PNG sheets decode through `pngjs`; WebP sheets
+     decode through `@jsquash/webp` (wasm, lazy-init). The idle cell
+     (row 0 col 0) is the source for both render paths below.
+
+   Then emit through one of two terminal output paths, picked
+   automatically per-terminal:
+   - **Inline graphics** (Kitty graphics protocol or iTerm2 inline
+     images). The cropped RGBA cell is re-encoded to PNG via `pngjs`
+     and handed to pi-tui's `Image` component, which transmits it as a
+     true-color bitmap. Used in Kitty, Ghostty, WezTerm, Konsole, and
+     iTerm2 — the terminal does its own scaling, so pixel-art sprites
+     stay crisp and codex pets render at full fidelity.
+   - **24-bit ANSI half-blocks** (universal fallback). Emits the
+     upper/lower half-block characters `▀`/`▄` with `\x1b[38;2;…m`
+     true-color escapes so each terminal cell paints two pixels. Used
+     in Apple Terminal, plain SSH, tmux without passthrough, and
+     anywhere that doesn't advertise inline-image support. Transparent
+     regions show pi's background through.
+
+   To force the half-block path even on a graphics-capable terminal
+   (handy for screenshots and demo recordings), set
+   `SIMOCRACY_INLINE_GRAPHICS=ansi`. The default is `auto`.
+
+   Both paths use the same upstream RGBA buffer — swapping between
+   them changes only the final encoding step, never the source pixels.
 5. **Inject.** A `before_agent_start` event handler appends the sim's
    identity + constitution + speaking style to pi's system prompt **every
    turn**. After `/sim unload`, a one-shot override fires on the next
@@ -129,15 +165,18 @@ keeps the terminal it's already running in.
 
 ```
 src/
-├── index.ts        # extension entry: slash command, tools, persona injection
-├── persona.ts      # buildSimPrompt(sim) — the system-prompt fragment
-├── simocracy.ts    # indexer + PDS client (read-only fetchers)
-├── writes.ts       # PDS writers + ownership / sign-in preconditions
-├── png-to-ansi.ts  # RGBA half-block ANSI renderer
-├── openrouter.ts   # minimal OpenRouter client (only used by simocracy_chat)
-└── auth/           # ATProto OAuth loopback flow + session storage
+├── index.ts          # extension entry: slash command, tools, persona injection
+├── persona.ts        # buildSimPrompt(sim) — the system-prompt fragment
+├── simocracy.ts      # indexer + PDS client (read-only fetchers)
+├── writes.ts         # PDS writers + ownership / sign-in preconditions
+├── png-to-ansi.ts    # RGBA half-block ANSI renderer + downscalers
+├── png-encode.ts     # RGBA → PNG encoder for inline-graphics protocols
+├── webp-to-rgba.ts   # @jsquash/webp wrapper for codex pet WebP sheets
+├── openrouter.ts     # minimal OpenRouter client (only used by simocracy_chat)
+└── auth/             # ATProto OAuth loopback flow + session storage
 demo/
-└── sim-load.tape   # vhs tape — render with `vhs demo/sim-load.tape`
+├── sim-load.tape       # vhs tape — Mr Meow (pipoya)
+└── codex-pet-load.tape # vhs tape — Einstein (codex pet)
 ```
 
 ---
@@ -153,11 +192,12 @@ pi -e $(pwd)/src/index.ts -ne -ns  # load the extension directly
 
 Then in `pi`: `/sim mr meow`.
 
-To rebuild the demo recording:
+To rebuild the demo recordings:
 
 ```bash
 brew install vhs                   # one-time
-vhs demo/sim-load.tape             # writes demo/sim-load.{webm,gif}
+vhs demo/sim-load.tape             # Mr Meow (pipoya) — demo/sim-load.{webm,gif}
+vhs demo/codex-pet-load.tape       # Einstein (codex pet) — demo/codex-pet-load.{webm,gif}
 ```
 
 ---
@@ -172,7 +212,11 @@ These come bundled with `pi` itself, so installing pi-simocracy via
 
 Direct npm dependencies (auto-installed):
 
-- `pngjs` — PNG decoder for sprite blobs
+- `pngjs` — PNG decoder for pipoya sprite blobs and codex pet PNG sheets
+- `@jsquash/webp` — wasm WebP decoder for codex pet WebP sheets
+  (lazy-init, no native bindings)
+- `@atproto/api` + `@atproto/oauth-client-node` — ATProto loopback OAuth
+  for `/sim login` and PDS writes via `simocracy_update_sim`
 - `typebox` — tool parameter schemas
 
 ---
@@ -192,4 +236,4 @@ Direct npm dependencies (auto-installed):
 
 ## License
 
-MIT — see [LICENSE](./LICENSE).
+MIT — see [LICENSE](https://github.com/GainForest/pi-simocracy/blob/main/LICENSE).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-simocracy",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Pi extension: load a Simocracy sim into your chat — see its pixel-art sprite render inline in the terminal and roleplay with it.",
   "type": "module",
   "author": "David Dao <david@gainforest.earth> (https://github.com/daviddao)",
@@ -45,6 +45,7 @@
   "dependencies": {
     "@atproto/api": "^0.19.11",
     "@atproto/oauth-client-node": "^0.3.17",
+    "@jsquash/webp": "^1.5.0",
     "pngjs": "^7.0.0",
     "typebox": "^1.1.24"
   },

package/src/index.ts

@@ -60,7 +60,15 @@ import type {
   ExtensionContext,
   ExtensionCommandContext,
 } from "@mariozechner/pi-coding-agent";
-import { Text } from "@mariozechner/pi-tui";
+import {
+  Box,
+  Image,
+  Text,
+  allocateImageId,
+  getCapabilities,
+  type ImageTheme,
+  type TUI,
+} from "@mariozechner/pi-tui";
 import { Type } from "typebox";
 
 import {
@@ -81,7 +89,10 @@ import {
   cropRgba,
   detectPixelArtScale,
   downscaleRgbaNearest,
+  boxDownscaleRgba,
 } from "./png-to-ansi.ts";
+import { encodeRgbaToPng } from "./png-encode.ts";
+import { decodeWebp } from "./webp-to-rgba.ts";
 import { openRouterComplete, type ChatMessage } from "./openrouter.ts";
 import { buildSimPrompt, type LoadedSim } from "./persona.ts";
 import { runLogin, runLogout, runWhoami } from "./auth/commands.ts";
@@ -111,6 +122,100 @@ let loadedSim: LoadedSim | null = null;
  */
 let justUnloaded: string | null = null;
 
+// ---------------------------------------------------------------------------
+// Animation state
+//
+// We animate the most recently loaded codex pet's idle row inline in chat,
+// using the same pattern pi-tui's spinner uses: a setInterval ticks a frame
+// counter and calls `tui.requestRender()`, which makes pi-tui re-run the
+// message renderer. Each render returns a new `Image` keyed by a stable
+// Kitty image ID, so the terminal swaps the displayed frame in place.
+//
+// Typing keeps working during animation — input handling and rendering are
+// independent code paths in pi-tui (verified by inspection of `Loader`).
+//
+// Only ONE sim animates at a time. When a new sim is loaded, the previous
+// timer stops and the previous message freezes on its idle frame.
+// ---------------------------------------------------------------------------
+
+/** Captured pi-tui handle. Set by the `simocracy` widget factory the first
+ *  time a sim is loaded; reused for every subsequent animation tick. Lazy
+ *  because the TUI doesn't exist when the extension first imports. */
+let capturedTui: TUI | null = null;
+
+interface ActiveAnimation {
+  /** Identifies which loaded-sim message owns this animation. The renderer
+   *  compares against `details.animationKey` to decide whether to use the
+   *  current frame or the static idle PNG. */
+  key: string;
+  /** Stable Kitty image ID so frame transmissions replace the previous one
+   *  instead of stacking. Allocated once per sim load. */
+  imageId: number;
+  /** Pre-encoded base64 PNGs in playback order. */
+  frames: string[];
+  /** Frame width / height in pixels (uniform across frames). */
+  widthPx: number;
+  heightPx: number;
+  /** Currently displayed frame index. */
+  currentFrame: number;
+  /** Active setInterval handle so we can clear it on unload / reload. */
+  intervalId: ReturnType<typeof setInterval> | null;
+}
+let currentAnimation: ActiveAnimation | null = null;
+
+/** Default-on; set `SIMOCRACY_ANIMATION=off` to freeze on idle frame 0. */
+const animationEnabled =
+  (process.env.SIMOCRACY_ANIMATION ?? "on").toLowerCase() !== "off";
+
+/**
+ * Width of the inline sprite render in terminal cells. The source PNG
+ * is always transmitted at native resolution (192×208 for codex pets,
+ * 32×32 for pipoya — see `renderSprite`); this number controls only
+ * how many cells the terminal uses to display it. Aspect ratio is
+ * preserved by pi-tui's `calculateImageRows`. Override with the
+ * `SIMOCRACY_SPRITE_WIDTH` env var.
+ *
+ * 10 cells wide gives a compact ≈6-row inline render that sits
+ * comfortably alongside one or two paragraphs of bio text without
+ * dominating the chat. Bump it to 20 or 32 if you want the sprite
+ * to read at a glance.
+ */
+const spriteWidthCells = (() => {
+  const raw = process.env.SIMOCRACY_SPRITE_WIDTH;
+  const parsed = raw ? Number.parseInt(raw, 10) : NaN;
+  return Number.isFinite(parsed) && parsed >= 4 && parsed <= 120 ? parsed : 10;
+})();
+
+function stopCurrentAnimation(): void {
+  if (currentAnimation?.intervalId !== null && currentAnimation?.intervalId !== undefined) {
+    clearInterval(currentAnimation.intervalId);
+  }
+  currentAnimation = null;
+}
+
+function startAnimationFor(key: string, frames: { pngBase64: string[]; fps: number; widthPx: number; heightPx: number }): void {
+  // Always replace any prior animation — only the most recent loaded-sim
+  // message animates.
+  stopCurrentAnimation();
+  if (!animationEnabled || frames.pngBase64.length < 2) return;
+  currentAnimation = {
+    key,
+    imageId: allocateImageId(),
+    frames: frames.pngBase64,
+    widthPx: frames.widthPx,
+    heightPx: frames.heightPx,
+    currentFrame: 0,
+    intervalId: null,
+  };
+  const intervalMs = Math.max(1000 / frames.fps, 60); // clamp to ≆16 fps max
+  currentAnimation.intervalId = setInterval(() => {
+    if (!currentAnimation) return;
+    currentAnimation.currentFrame =
+      (currentAnimation.currentFrame + 1) % currentAnimation.frames.length;
+    capturedTui?.requestRender();
+  }, intervalMs);
+}
+
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
@@ -124,19 +229,104 @@ function blobLink(ref: unknown): string | null {
 }
 
 /**
- * Render a sim's sprite at its native 32×32 size as colored ANSI
- * half-block art — 16 cells tall, 32 cells wide. Compact enough to fit
- * comfortably in a terminal alongside the loaded-sim message.
+ * Maximum long-edge of a non-pixel-art avatar before we box-downscale it.
+ * Picked so codex pet idle frames render at roughly the same on-screen
+ * height as a 32×32 pipoya sprite (~17 terminal lines) instead of
+ * ballooning to 60+ lines and pushing the rest of chat off-screen.
+ */
+const NON_PIXEL_ART_TARGET_LONG_EDGE = 40;
+
+/**
+ * Render a sim's avatar as colored ANSI half-block art, sized to fit
+ * comfortably alongside the loaded-sim message in a typical terminal.
+ *
+ * Branches on `spriteKind` (lexicon discriminator):
  *
- * Pulls the front-facing walk1 frame (row 0, col 0) from the 128×128
- * sprite-sheet blob. Falls back to the static avatar PNG if no sheet
- * is published for this sim.
+ *   pipoya   — fetch the 4×4 walk-sheet PNG, crop the front-facing
+ *              walk-1 frame (32×32, row 0 col 0), render at native
+ *              resolution. ~16 lines tall.
+ *
+ *   codexPet — prefer the 8×9 atlas (`petSheet`, 1536×1872, 192×208
+ *              cells) when it's PNG: crop the idle cell (row 0 col 0)
+ *              and box-downscale to ~32 wide. The atlas is usually WebP
+ *              (the OpenAI hatch-pet skill emits WebP and `pngjs`
+ *              doesn't speak WebP), so we fall through to the rendered
+ *              `image` thumbnail — a PNG that the simocracy.org client
+ *              generates at 128×128 from the idle frame. That gets
+ *              box-downscaled to a comparable terminal size.
+ *
+ *   absent   — treated as legacy 'pipoya' for back-compat.
+ *
+ * Returns BOTH the ANSI half-block render (always — it's our universal
+ * fallback) AND, when possible, a PNG of the same RGBA cell for inline
+ * terminal-graphics protocols (Kitty / iTerm2). The renderer chooses
+ * which to display based on the host terminal's capabilities.
+ *
+ * The PNG is encoded at the *native* resolution we cropped to (32×32
+ * for pipoya, 192×208 for codexPet, the post-downscale size for the
+ * image fallback). Kitty / iTerm2 do their own scaling to the target
+ * cell box, so passing the native pixels gives the terminal the most
+ * information to work with — pixel art scales up crisply with
+ * nearest-neighbour, codex pet thumbnails scale down cleanly.
+ */
+export interface SpriteRender {
+  ansi: string;
+  png?: { data: Buffer; widthPx: number; heightPx: number };
+  /**
+   * Optional animation frames. Each entry in `pngs` is a PNG of one
+   * cell. Set for codex pets (idle row of their atlas); absent for
+   * everything else (pipoya sprites and image fallbacks render as a
+   * single static frame). The renderer plays these in a loop using
+   * the Kitty in-place image-swap protocol when animation is enabled.
+   */
+  frames?: { pngs: Buffer[]; widthPx: number; heightPx: number; fps: number };
+}
+
+/**
+ * Codex pet atlas constants — keep in sync with the simocracy-v2 hatch-pet
+ * skill that produces these sheets. The atlas is 8 cols × 9 rows of
+ * 192×208 cells; the idle animation lives on row 0, frames 0–5 (the same
+ * default tui-pets ships when a pet.json doesn't override it).
  */
-async function renderSpriteAnsi(sim: SimMatch): Promise<string | null> {
+const CODEX_PET_CELL_W = 192;
+const CODEX_PET_CELL_H = 208;
+const CODEX_PET_COLS = 8;
+const CODEX_PET_IDLE_FRAMES = [0, 1, 2, 3, 4, 5];
+const CODEX_PET_IDLE_FPS = 5;
+
+async function renderSprite(sim: SimMatch): Promise<SpriteRender | null> {
+  const spriteKind = sim.sim.spriteKind ?? "pipoya";
   const spriteLink = blobLink(sim.sim.sprite?.ref);
+  const petSheetLink = blobLink(sim.sim.petSheet?.ref);
+  const petSheetMime = sim.sim.petSheet?.mimeType;
   const imageLink = blobLink(sim.sim.image?.ref);
 
-  if (spriteLink) {
+  /** Render an RGBA region to ANSI half-blocks (shared options). */
+  const toAnsi = (data: Buffer, width: number, height: number) =>
+    renderRgbaToAnsi(data, width, height, {
+      cropToContent: true,
+      cropPad: 1,
+      indent: 2,
+      alphaThreshold: 16,
+    });
+
+  /** Bundle ANSI + PNG of the same RGBA region. PNG-encode is a tiny
+   *  cost and is wrapped in try/catch — if encoding ever fails we
+   *  still return the ANSI render (lossless fallback). */
+  const bundle = (data: Buffer, width: number, height: number): SpriteRender => {
+    const ansi = toAnsi(data, width, height);
+    let png: SpriteRender["png"];
+    try {
+      const pngBytes = encodeRgbaToPng(data, width, height);
+      png = { data: pngBytes, widthPx: width, heightPx: height };
+    } catch {
+      png = undefined;
+    }
+    return { ansi, png };
+  };
+
+  // Pipoya 4×4 walk sheet — the legacy/default path.
+  if (spriteKind !== "codexPet" && spriteLink) {
     try {
       const buf = await fetchBlob(sim.did, spriteLink);
       const { width, height, data } = decodePng(buf);
@@ -144,43 +334,116 @@ async function renderSpriteAnsi(sim: SimMatch): Promise<string | null> {
       if (width >= FRAME && height >= FRAME) {
         // Sheets are 4×4 of 32×32 frames — row 0 col 0 = front-facing walk1.
         const frame = cropRgba(data, width, height, 0, 0, FRAME, FRAME);
-        return renderRgbaToAnsi(frame, FRAME, FRAME, {
-          cropToContent: true,
-          cropPad: 1,
-          indent: 2,
-          alphaThreshold: 16,
-        });
+        return bundle(frame, FRAME, FRAME);
+      }
+      return bundle(data, width, height);
+    } catch {
+      /* fall through to image fallback */
+    }
+  }
+
+  // Codex pet atlas — the canonical asset for codex pets. Sheets are
+  // 1536×1872 with 192×208 cells laid out 8 cols × 9 rows; row 0 col 0
+  // is the idle frame. Both PNG and WebP are valid in the lexicon (the
+  // hatch-pet skill emits WebP, the dropzone preserves PNG when the
+  // user drops a PNG sheet) so we pick the right decoder by mimeType.
+  // We crop the idle cell first thing. For the ANSI render we
+  // box-downscale to ~32 wide so the inline render is similar in
+  // height to a pipoya sprite (~17 lines). For the inline-graphics
+  // PNG we keep the native 192×208 resolution — Kitty / iTerm2 will
+  // scale it down at display time, which preserves more detail than
+  // pre-downscaling here.
+  if (spriteKind === "codexPet" && petSheetLink) {
+    try {
+      const buf = await fetchBlob(sim.did, petSheetLink);
+      const { width, height, data } =
+        petSheetMime === "image/webp" ? await decodeWebp(buf) : decodePng(buf);
+      const CELL_W = 192;
+      const CELL_H = 208;
+      if (width >= CELL_W && height >= CELL_H) {
+        const cell = cropRgba(data, width, height, 0, 0, CELL_W, CELL_H);
+        const targetW = 32;
+        const targetH = Math.round((CELL_H / CELL_W) * targetW); // ~35
+        const scaled = boxDownscaleRgba(cell, CELL_W, CELL_H, targetW, targetH);
+        const ansi = toAnsi(scaled.data, scaled.width, scaled.height);
+        let png: SpriteRender["png"];
+        try {
+          const pngBytes = encodeRgbaToPng(cell, CELL_W, CELL_H);
+          png = { data: pngBytes, widthPx: CELL_W, heightPx: CELL_H };
+        } catch {
+          png = undefined;
+        }
+
+        // Idle animation frames — same atlas, different cell offsets.
+        // Encoded eagerly here so the message renderer can flip
+        // between them at ~5 FPS without re-decoding the WebP. Wrapped
+        // in its own try/catch — a frame-encoding failure shouldn't
+        // disable the static render.
+        let frames: SpriteRender["frames"];
+        try {
+          const framePngs: Buffer[] = [];
+          for (const idx of CODEX_PET_IDLE_FRAMES) {
+            const cx = (idx % CODEX_PET_COLS) * CELL_W;
+            const cy = Math.floor(idx / CODEX_PET_COLS) * CELL_H;
+            // Skip frames that fall outside the actual atlas extent.
+            if (cx + CELL_W > width || cy + CELL_H > height) continue;
+            const frameCell = cropRgba(data, width, height, cx, cy, CELL_W, CELL_H);
+            framePngs.push(encodeRgbaToPng(frameCell, CELL_W, CELL_H));
+          }
+          // Single-frame "animations" are pointless — leave `frames`
+          // unset so the renderer takes the static path. Two or more
+          // = a real loop.
+          if (framePngs.length >= 2) {
+            frames = {
+              pngs: framePngs,
+              widthPx: CELL_W,
+              heightPx: CELL_H,
+              fps: CODEX_PET_IDLE_FPS,
+            };
+          }
+        } catch {
+          frames = undefined;
+        }
+        return { ansi, png, frames };
       }
-      return renderRgbaToAnsi(data, width, height, {
-        cropToContent: true,
-        cropPad: 1,
-        indent: 2,
-        alphaThreshold: 16,
-      });
     } catch {
-      /* fall through to avatar */
+      /* fall through to image fallback */
     }
   }
 
+  // Image fallback — used when a sim has no walk sheet (legacy pipoya
+  // sims that pre-date `org.simocracy.sim.sprite`) or when the codex
+  // pet atlas decode failed for any reason. The simocracy.org client
+  // always generates a 128×128 PNG idle thumbnail and uploads it as
+  // `image` for codex pets, so even when this path runs the right pose
+  // shows up.
   if (imageLink) {
     try {
       const buf = await fetchBlob(sim.did, imageLink);
       const { width, height, data } = decodePng(buf);
-      // Old sims (pre-sprite-sheet) only have the avatar PNG, which
-      // simocracy.org renders by 4×-upscaling a native 32×32 sprite into
-      // a 128×128 image with nearest-neighbour. Detect that and downsample
-      // back to the original size so the inline render is the same
-      // ~13-line height as a sprite-sheet-equipped sim instead of
-      // ballooning to ~22 lines and pushing chat off-screen.
+      // Old pipoya sims publish a 128×128 PNG that's a 4×-upscaled 32×32
+      // pixel-art sprite. Detect and undo that with nearest-neighbour
+      // downsampling.
       const scale = detectPixelArtScale(data, width, height, 8);
-      const native =
-        scale > 1 ? downscaleRgbaNearest(data, width, height, scale) : { data, width, height };
-      return renderRgbaToAnsi(native.data, native.width, native.height, {
-        cropToContent: true,
-        cropPad: 1,
-        indent: 2,
-        alphaThreshold: 16,
-      });
+      let native: { data: Buffer; width: number; height: number } =
+        scale > 1
+          ? downscaleRgbaNearest(data, width, height, scale)
+          : { data, width, height };
+      // Non-pixel-art images (codex pet thumbnails, avatars from other
+      // pipelines) come through at full resolution — box-downscale them
+      // so the ANSI render fits in a typical terminal row budget.
+      const longEdge = Math.max(native.width, native.height);
+      if (scale === 1 && longEdge > NON_PIXEL_ART_TARGET_LONG_EDGE) {
+        const k = NON_PIXEL_ART_TARGET_LONG_EDGE / longEdge;
+        native = boxDownscaleRgba(
+          native.data,
+          native.width,
+          native.height,
+          Math.max(1, Math.round(native.width * k)),
+          Math.max(1, Math.round(native.height * k)),
+        );
+      }
+      return bundle(native.data, native.width, native.height);
     } catch {
       /* fall through */
     }
@@ -207,10 +470,10 @@ async function loadSimByName(query: string): Promise<{
 
 async function hydrateLoadedSim(match: SimMatch): Promise<LoadedSim> {
   // Fetch agents (constitution), style, sprite ANSI + handle in parallel.
-  const [agents, style, spriteAnsi, handle] = await Promise.all([
+  const [agents, style, sprite, handle] = await Promise.all([
     fetchAgentsForSim(match.uri).catch(() => null) as Promise<AgentsRecord | null>,
     fetchStyleForSim(match.uri).catch(() => null) as Promise<StyleRecord | null>,
-    renderSpriteAnsi(match).catch(() => null),
+    renderSprite(match).catch(() => null),
     resolveHandle(match.did).catch(() => null),
   ]);
 
@@ -220,14 +483,36 @@ async function hydrateLoadedSim(match: SimMatch): Promise<LoadedSim> {
     rkey: match.rkey,
     name: match.sim.name,
     handle,
-    spriteAnsi: spriteAnsi ?? undefined,
+    spriteAnsi: sprite?.ansi,
+    spritePng: sprite?.png
+      ? {
+          base64: sprite.png.data.toString("base64"),
+          widthPx: sprite.png.widthPx,
+          heightPx: sprite.png.heightPx,
+        }
+      : undefined,
+    spriteFrames: sprite?.frames
+      ? {
+          pngBase64: sprite.frames.pngs.map((b) => b.toString("base64")),
+          fps: sprite.frames.fps,
+          widthPx: sprite.frames.widthPx,
+          heightPx: sprite.frames.heightPx,
+        }
+      : undefined,
     shortDescription: agents?.shortDescription,
     description: agents?.description,
     style: style?.description,
   };
 }
 
-function formatSimSummary(
+/**
+ * Build the bio text block that appears alongside (or below) the
+ * sprite in the loaded-sim message: name + handle + AT-URI +
+ * shortDescription. Indented two spaces so it lines up with the ANSI
+ * sprite render. Used both as a standalone block (Image+Text
+ * variant) and as the trailing portion of `formatSimSummary`.
+ */
+function formatSimBio(
   sim: LoadedSim,
   theme?: ExtensionContext["ui"]["theme"],
 ): string {
@@ -236,10 +521,6 @@ function formatSimSummary(
     ? (s: string) => theme.fg("accent", s)
     : (s: string) => s;
   const lines: string[] = [];
-  if (sim.spriteAnsi) {
-    lines.push(sim.spriteAnsi);
-    lines.push("");
-  }
   lines.push(`  🐾 ${accent(sim.name)}${sim.handle ? dim(`  @${sim.handle}`) : ""} loaded—pi is now in character.`);
   lines.push(dim(`  ${sim.uri}`));
   if (sim.shortDescription) {
@@ -249,6 +530,19 @@ function formatSimSummary(
   return lines.join("\n");
 }
 
+function formatSimSummary(
+  sim: LoadedSim,
+  theme?: ExtensionContext["ui"]["theme"],
+): string {
+  const lines: string[] = [];
+  if (sim.spriteAnsi) {
+    lines.push(sim.spriteAnsi);
+    lines.push("");
+  }
+  lines.push(formatSimBio(sim, theme));
+  return lines.join("\n");
+}
+
 // The OpenTUI standalone animated viewer used to live here. It now ships
 // alongside this file as `viewer.ts` for anyone who wants the full-window
 // experience — run it manually with:
@@ -334,11 +628,90 @@ export default async function simocracy(pi: ExtensionAPI) {
 
   // -------------------------------------------------------------------------
   // Custom message renderer — shows the sprite + bio inline in the chat.
+  //
+  // Two render paths, picked per-call:
+  //
+  //   1. Inline graphics (preferred when supported). Terminals that
+  //      advertise the Kitty graphics protocol (Kitty, Ghostty, WezTerm,
+  //      Konsole) or iTerm2's inline-image protocol get a real PNG of
+  //      the sprite via pi-tui's `Image` component, stacked above the
+  //      bio text in a `Box`. Pixels are crisp, scaling is the
+  //      terminal's job.
+  //
+  //   2. ANSI half-blocks (universal fallback). Everything else —
+  //      Apple Terminal, tmux without passthrough, plain SSH, dumb
+  //      pipes — falls back to the existing `▀`/`▄` half-block art.
+  //
+  // Override with `SIMOCRACY_INLINE_GRAPHICS=ansi` to force the
+  // half-block path even when the terminal supports inline graphics
+  // (handy for screenshots, demo recordings, or terminals that
+  // *advertise* support but render glitchily).
   // -------------------------------------------------------------------------
-  pi.registerMessageRenderer<{ body: string }>("simocracy_sim_loaded", (message) => {
+  const inlineGraphicsMode =
+    (process.env.SIMOCRACY_INLINE_GRAPHICS ?? "auto").toLowerCase();
+  pi.registerMessageRenderer<SimLoadedDetails>("simocracy_sim_loaded", (message, _opts, theme) => {
+    const details = (message.details as SimLoadedDetails | undefined) ?? {};
     const body =
-      (message.details as { body?: string } | undefined)?.body ??
-      (typeof message.content === "string" ? message.content : "");
+      details.body ?? (typeof message.content === "string" ? message.content : "");
+
+    // Decide whether to use the inline-graphics path. Auto-detect by
+    // default; honour the env-var override either direction.
+    const caps = getCapabilities();
+    const wantGraphics =
+      inlineGraphicsMode === "auto"
+        ? caps.images !== null
+        : inlineGraphicsMode === "kitty" || inlineGraphicsMode === "iterm2";
+    if (wantGraphics && details.spritePngBase64 && details.bioText) {
+      // Pi-tui's Image needs a fallback colour for terminals that
+      // claim image support but later fail to render — we use the
+      // theme's `dim` so the placeholder text is unobtrusive.
+      const imageTheme: ImageTheme = {
+        fallbackColor: theme.fg("dim", "") ? (s: string) => theme.fg("dim", s) : (s: string) => s,
+      };
+      // Animation handoff: if there's an active animation AND it's
+      // for this exact message (matching animationKey), pull the
+      // current frame's PNG + the stable Kitty image ID. The image
+      // ID makes successive frame transmissions replace each other
+      // in place rather than stacking. For everything else (older
+      // loaded-sim messages, sims without animation frames) we use
+      // the static idle PNG with no image ID, so they freeze
+      // gracefully on the first frame.
+      let pngBase64 = details.spritePngBase64;
+      let imageOptions: { maxWidthCells: number; imageId?: number } = {
+        maxWidthCells: spriteWidthCells,
+      };
+      let imageDims = {
+        widthPx: details.spritePngWidth ?? 0,
+        heightPx: details.spritePngHeight ?? 0,
+      };
+      if (
+        currentAnimation &&
+        details.animationKey &&
+        currentAnimation.key === details.animationKey
+      ) {
+        pngBase64 = currentAnimation.frames[currentAnimation.currentFrame] ?? pngBase64;
+        imageOptions = {
+          maxWidthCells: spriteWidthCells,
+          imageId: currentAnimation.imageId,
+        };
+        imageDims = { widthPx: currentAnimation.widthPx, heightPx: currentAnimation.heightPx };
+      }
+      // Source PNG is at full native resolution (192×208 for codex
+      // pets, 32×32 for pipoya). The terminal scales it down to
+      // `spriteWidthCells` cells wide on display — we never
+      // pre-downsample on our side, so quality is preserved.
+      const image = new Image(
+        pngBase64,
+        "image/png",
+        imageTheme,
+        imageOptions,
+        imageDims,
+      );
+      const box = new Box(0, 0);
+      box.addChild(image);
+      box.addChild(new Text(details.bioText, 0, 0));
+      return box;
+    }
     return new Text(body, 0, 0);
   });
 
@@ -411,6 +784,7 @@ export default async function simocracy(pi: ExtensionAPI) {
         const name = loadedSim.name;
         loadedSim = null;
         justUnloaded = name;
+        stopCurrentAnimation();
         ctx.ui.setStatus("simocracy", undefined);
         ctx.ui.setWidget("simocracy", undefined);
         ctx.ui.notify(`Unloaded ${name}. Pi will break character on the next reply.`, "info");
@@ -500,6 +874,7 @@ export default async function simocracy(pi: ExtensionAPI) {
       const name = loadedSim.name;
       loadedSim = null;
       justUnloaded = name;
+      stopCurrentAnimation();
       if (ctx.hasUI) {
         ctx.ui.setStatus("simocracy", undefined);
         ctx.ui.setWidget("simocracy", undefined);
@@ -942,8 +1317,11 @@ async function tryLoadFromQuery(query: string): Promise<LoadedSim | null> {
       const { getRecordFromPds } = await import("./simocracy.ts");
       const sim = await getRecordFromPds<{
         name: string;
-        image?: { ref: unknown };
-        sprite?: { ref: unknown };
+        spriteKind?: "pipoya" | "codexPet";
+        image?: { ref: unknown; mimeType: string; size: number };
+        sprite?: { ref: unknown; mimeType: string; size: number };
+        petSheet?: { ref: unknown; mimeType: string; size: number };
+        petManifest?: { id?: string; displayName?: string; description?: string };
         $type?: string;
       }>(did, "org.simocracy.sim", rkey);
       const match: SimMatch = {
@@ -954,9 +1332,12 @@ async function tryLoadFromQuery(query: string): Promise<LoadedSim | null> {
         sim: {
           $type: "org.simocracy.sim",
           name: sim.name,
+          spriteKind: sim.spriteKind,
           settings: { selectedOptions: {} },
           image: sim.image as never,
           sprite: sim.sprite as never,
+          petSheet: sim.petSheet as never,
+          petManifest: sim.petManifest,
           createdAt: "",
         },
       };
@@ -970,6 +1351,41 @@ async function tryLoadFromQuery(query: string): Promise<LoadedSim | null> {
   return await hydrateLoadedSim(result.matches[0]);
 }
 
+/**
+ * Shape of `details` on the `simocracy_sim_loaded` custom message.
+ * The renderer reads this to choose between the inline-graphics and
+ * ANSI-half-block render paths; both fields are best-effort — the
+ * renderer falls back to the combined `body` string if anything is
+ * missing.
+ */
+interface SimLoadedDetails {
+  uri?: string;
+  did?: string;
+  rkey?: string;
+  name?: string;
+  /** Combined ANSI sprite + bio, used by the half-block fallback path
+   *  and as the textual log content. */
+  body?: string;
+  /** Bio text only (no sprite), used alongside the Image component
+   *  on the inline-graphics path. */
+  bioText?: string;
+  /** base64-encoded PNG of the sprite cell. Triggers the inline-graphics
+   *  path when set + the terminal advertises image support. */
+  spritePngBase64?: string;
+  /** Native PNG width in pixels (aspect ratio for Image scaling). */
+  spritePngWidth?: number;
+  /** Native PNG height in pixels. */
+  spritePngHeight?: number;
+  /**
+   * Identity tag for the active animation, if any. The message renderer
+   * compares against `currentAnimation.key` to decide whether to swap
+   * in the current animation frame or freeze on the static idle PNG.
+   * Stable across re-renders of the same message; differs across
+   * separate sim loads.
+   */
+  animationKey?: string;
+}
+
 async function postSimToChat(
   pi: ExtensionAPI,
   ctx: ExtensionContext,
@@ -977,21 +1393,54 @@ async function postSimToChat(
   _reload: boolean,
 ) {
   ctx.ui.setStatus("simocracy", `🐾 ${sim.name}`);
-  const headerLines = [`Simocracy: ${sim.name}${sim.handle ? `  (@${sim.handle})` : ""}`];
-  ctx.ui.setWidget("simocracy", headerLines, { placement: "aboveEditor" });
+  // Use the factory form of setWidget so we can capture pi-tui's TUI
+  // handle. We need it to call `requestRender()` from the animation
+  // setInterval (the message renderer doesn't get a TUI reference).
+  // The factory itself returns a tiny static Text widget — the TUI
+  // capture is the actual purpose.
+  const headerText = `Simocracy: ${sim.name}${sim.handle ? `  (@${sim.handle})` : ""}`;
+  ctx.ui.setWidget(
+    "simocracy",
+    (tui) => {
+      capturedTui = tui;
+      return new Text(headerText, 0, 0);
+    },
+    { placement: "aboveEditor" },
+  );
   const body = formatSimSummary(sim, ctx.ui.theme);
+  const bioText = formatSimBio(sim, ctx.ui.theme);
+  // Unique key per load so the renderer can tell which message owns
+  // the active animation. AT-URI + timestamp protects against
+  // re-loading the same sim twice (each load starts its own loop).
+  const animationKey = `${sim.uri}#${Date.now()}`;
+  const details: SimLoadedDetails = {
+    uri: sim.uri,
+    did: sim.did,
+    rkey: sim.rkey,
+    name: sim.name,
+    body,
+    bioText,
+    animationKey,
+  };
+  if (sim.spritePng) {
+    details.spritePngBase64 = sim.spritePng.base64;
+    details.spritePngWidth = sim.spritePng.widthPx;
+    details.spritePngHeight = sim.spritePng.heightPx;
+  }
   pi.sendMessage({
     customType: "simocracy_sim_loaded",
     content: stripAnsiForLog(body),
     display: true,
-    details: {
-      uri: sim.uri,
-      did: sim.did,
-      rkey: sim.rkey,
-      name: sim.name,
-      body,
-    },
+    details,
   });
+  // Kick off (or replace) the animation loop. Only one loop runs at a
+  // time — the last loaded sim animates, earlier messages freeze on
+  // their idle frame.
+  if (sim.spriteFrames) {
+    startAnimationFor(animationKey, sim.spriteFrames);
+  } else {
+    stopCurrentAnimation();
+  }
 }
 
 /** Strip ANSI escapes for the textual log copy (the renderer uses details.body). */

package/src/persona.ts

@@ -18,6 +18,43 @@ export interface LoadedSim {
   style?: string;
   /** Pre-rendered colored ANSI art of the sim's sprite. */
   spriteAnsi?: string;
+  /**
+   * Pre-encoded PNG of the sim's sprite (idle frame), for inline
+   * terminal graphics protocols (Kitty, iTerm2). Present when sprite
+   * rendering succeeded and the source could be encoded; the renderer
+   * uses this when the host terminal advertises image support and
+   * falls back to `spriteAnsi` otherwise.
+   */
+  spritePng?: {
+    /** base64-encoded PNG bytes (no `data:` prefix). */
+    base64: string;
+    /** Native PNG width in pixels (used for aspect ratio). */
+    widthPx: number;
+    /** Native PNG height in pixels. */
+    heightPx: number;
+  };
+  /**
+   * Pre-encoded PNG frames of the sim's idle animation, for terminals
+   * that support inline graphics. When present **and** the renderer's
+   * animation timer is active for this sim, the message renderer
+   * cycles through these instead of repeating `spritePng` — producing
+   * a gentle in-chat idle loop using the same Kitty-protocol
+   * in-place image swap that pi-tui's spinner uses to animate.
+   *
+   * Currently populated only for `codexPet` sims (their atlas defines
+   * an explicit 6-frame idle row); pipoya and image-fallback sims
+   * stay static.
+   */
+  spriteFrames?: {
+    /** base64-encoded PNG bytes per frame, in display order. */
+    pngBase64: string[];
+    /** Display rate in frames-per-second. */
+    fps: number;
+    /** Native PNG width in pixels (uniform across all frames). */
+    widthPx: number;
+    /** Native PNG height in pixels. */
+    heightPx: number;
+  };
 }
 
 /**

package/src/png-encode.ts

@@ -0,0 +1,29 @@
+/**
+ * Encode an RGBA pixel buffer to a PNG (`Buffer`) for inline terminal
+ * graphics protocols (Kitty, iTerm2). Both protocols accept base64-PNG
+ * payloads — Kitty supports it via `f=100`, iTerm2 via `inline=1`.
+ *
+ * Sized to be tiny: the only operation here is wrapping `pngjs`'s
+ * synchronous packer in a typed helper that matches the
+ * decoder/cropper interfaces in `png-to-ansi.ts`. We never need
+ * streaming or async — the largest image we encode is a 192×208 codex
+ * pet idle cell (~30 KB PNG).
+ */
+
+import { PNG } from "pngjs";
+
+/**
+ * Encode a flat RGBA8 buffer to PNG. `data.length` must equal
+ * `width * height * 4`. Returns a fresh `Buffer` containing the PNG
+ * bytes (signature `89 50 4e 47 …`).
+ */
+export function encodeRgbaToPng(data: Buffer, width: number, height: number): Buffer {
+  if (data.length !== width * height * 4) {
+    throw new Error(
+      `encodeRgbaToPng: expected ${width * height * 4} bytes for ${width}×${height}, got ${data.length}`,
+    );
+  }
+  const png = new PNG({ width, height });
+  data.copy(png.data);
+  return PNG.sync.write(png);
+}

package/src/png-to-ansi.ts

@@ -235,6 +235,85 @@ export function downscaleRgbaNearest(
   return { data: out, width: newW, height: newH };
 }
 
+/**
+ * Box-average downscale an RGBA buffer to arbitrary target dimensions.
+ *
+ * Uses straight area-weighted averaging on premultiplied alpha so partly
+ * transparent edge pixels don't bleed black into the result. Designed for
+ * non-pixel-art inputs (codex pet idle thumbnails, codex pet sheet cells)
+ * where we want a smaller display size at non-integer ratios.
+ *
+ * If the target equals the source size, returns the input untouched.
+ */
+export function boxDownscaleRgba(
+  data: Buffer,
+  width: number,
+  height: number,
+  targetW: number,
+  targetH: number,
+): { data: Buffer; width: number; height: number } {
+  if (targetW < 1 || targetH < 1) {
+    throw new Error(`boxDownscaleRgba target must be ≥1×1, got ${targetW}×${targetH}`);
+  }
+  if (targetW === width && targetH === height) {
+    return { data, width, height };
+  }
+  const out = Buffer.alloc(targetW * targetH * 4);
+  // For each output pixel, average the source rectangle that maps to it.
+  // Edge cells are clamped to the source extent.
+  for (let oy = 0; oy < targetH; oy++) {
+    const sy0 = (oy * height) / targetH;
+    const sy1 = ((oy + 1) * height) / targetH;
+    const y0 = Math.floor(sy0);
+    const y1 = Math.min(height, Math.ceil(sy1));
+    for (let ox = 0; ox < targetW; ox++) {
+      const sx0 = (ox * width) / targetW;
+      const sx1 = ((ox + 1) * width) / targetW;
+      const x0 = Math.floor(sx0);
+      const x1 = Math.min(width, Math.ceil(sx1));
+
+      // Premultiplied accumulation so transparent pixels don't smear
+      // black RGB values into mostly-opaque neighbours.
+      let rSum = 0,
+        gSum = 0,
+        bSum = 0,
+        aSum = 0,
+        wSum = 0;
+      for (let y = y0; y < y1; y++) {
+        // Vertical coverage of this source row inside the output cell.
+        const wy = Math.min(y + 1, sy1) - Math.max(y, sy0);
+        if (wy <= 0) continue;
+        for (let x = x0; x < x1; x++) {
+          const wx = Math.min(x + 1, sx1) - Math.max(x, sx0);
+          if (wx <= 0) continue;
+          const w = wx * wy;
+          const i = (y * width + x) * 4;
+          const a = data[i + 3];
+          const aw = a * w;
+          rSum += data[i] * aw;
+          gSum += data[i + 1] * aw;
+          bSum += data[i + 2] * aw;
+          aSum += aw;
+          wSum += w;
+        }
+      }
+      const di = (oy * targetW + ox) * 4;
+      if (aSum > 0) {
+        out[di] = Math.min(255, Math.round(rSum / aSum));
+        out[di + 1] = Math.min(255, Math.round(gSum / aSum));
+        out[di + 2] = Math.min(255, Math.round(bSum / aSum));
+        out[di + 3] = Math.min(255, Math.round(aSum / wSum));
+      } else {
+        out[di] = 0;
+        out[di + 1] = 0;
+        out[di + 2] = 0;
+        out[di + 3] = 0;
+      }
+    }
+  }
+  return { data: out, width: targetW, height: targetH };
+}
+
 /**
  * Detect the integer upscale factor of a pixel-art image by scanning
  * for the largest factor F where every F×F block has uniform colour.

package/src/simocracy.ts

@@ -24,13 +24,33 @@ export interface BlobRef {
   size: number;
 }
 
+/** Which sprite system a sim uses. Absent = legacy 'pipoya'. */
+export type SpriteKind = "pipoya" | "codexPet";
+
+/** Subset of pet.json from the OpenAI hatch-pet skill output. */
+export interface CodexPetManifest {
+  id?: string;
+  displayName?: string;
+  description?: string;
+}
+
 export interface SimRecord {
   $type: "org.simocracy.sim";
   name: string;
-  settings: SpriteSettings;
+  /** Discriminator for sprite system. Absent = 'pipoya'. */
+  spriteKind?: SpriteKind;
+  /** Pipoya appearance settings (only used when spriteKind = 'pipoya'). */
+  settings?: SpriteSettings;
+  /** Rendered avatar PNG/JPEG/WebP thumbnail (always present for codex pets, generated client-side as a 128×128 PNG). */
   image?: BlobRef;
+  /** Pipoya 4×4 walk sheet (128×128 PNG). Only present when spriteKind = 'pipoya'. */
   sprite?: BlobRef;
+  /** Codex pet 8×9 atlas (1536×1872, 192×208 cells, PNG or WebP). Only present when spriteKind = 'codexPet'. */
+  petSheet?: BlobRef;
+  /** Subset of pet.json from the hatch-pet skill output. Only present when spriteKind = 'codexPet'. */
+  petManifest?: CodexPetManifest;
   createdAt: string;
+  updatedAt?: string;
 }
 
 export interface AgentsRecord {

package/src/webp-to-rgba.ts

@@ -0,0 +1,70 @@
+/**
+ * WebP → RGBA decoder for Node.
+ *
+ * `pngjs` covers the PNG side of pi-simocracy, but the OpenAI hatch-pet
+ * skill (and therefore most `org.simocracy.sim` records with
+ * `spriteKind = "codexPet"`) ships its 1536×1872 atlas as WebP. We need
+ * a WebP decoder to render the idle frame.
+ *
+ * @jsquash/webp's `decode()` is browser-shaped: in Node its wasm glue
+ * tries to `fetch()` its own `.wasm` URL, which Undici rejects for
+ * `file://`. Workaround: read the wasm bytes from disk via
+ * `createRequire().resolve()`, compile to a `WebAssembly.Module`, and
+ * feed it to the package's documented `init()` escape hatch. Fully ESM,
+ * no native bindings.
+ *
+ * The wasm module is initialised lazily on the first `decodeWebp()`
+ * call so loading pi-simocracy stays cheap when no one ever loads a
+ * codex pet sim. Subsequent calls reuse the same module.
+ */
+
+import { createRequire } from "node:module";
+import { readFile } from "node:fs/promises";
+import decode, { init as initWebpDecode } from "@jsquash/webp/decode.js";
+
+let wasmInitPromise: Promise<void> | null = null;
+
+async function ensureWasmInit(): Promise<void> {
+  if (wasmInitPromise) return wasmInitPromise;
+  wasmInitPromise = (async () => {
+    const require = createRequire(import.meta.url);
+    // @jsquash/webp ships the decoder wasm next to its JS glue; the
+    // package only re-exports JS files, so we have to resolve the wasm
+    // path manually. Resolving against the JS entry guarantees we hit
+    // the same install of the package the bundler/linker picked.
+    const decodeJs = require.resolve("@jsquash/webp/decode.js");
+    const wasmPath = decodeJs.replace(/decode\.js$/, "codec/dec/webp_dec.wasm");
+    const bytes = await readFile(wasmPath);
+    const mod = await WebAssembly.compile(bytes);
+    await initWebpDecode(mod);
+  })().catch((err) => {
+    // Reset so the next caller can retry; otherwise a transient FS
+    // error would permanently break codex-pet rendering for the session.
+    wasmInitPromise = null;
+    throw new Error(`Failed to init @jsquash/webp wasm: ${(err as Error).message}`);
+  });
+  return wasmInitPromise;
+}
+
+/**
+ * Decode a WebP buffer into the same flat-RGBA shape `decodePng()`
+ * returns, so call sites can treat the two interchangeably.
+ *
+ * Allocates a fresh `Buffer` rather than aliasing `Uint8ClampedArray`
+ * so downstream `Buffer`-only helpers (`pixelAt`, `cropRgba`,
+ * `boxDownscaleRgba`) keep working without coercion.
+ */
+export async function decodeWebp(
+  buf: Buffer,
+): Promise<{ width: number; height: number; data: Buffer }> {
+  await ensureWasmInit();
+  // jSquash wants an ArrayBuffer view of just the relevant bytes —
+  // passing the whole underlying buffer mis-decodes if `buf` is a slice.
+  const ab = buf.buffer.slice(buf.byteOffset, buf.byteOffset + buf.byteLength);
+  const img = await decode(ab as ArrayBuffer);
+  return {
+    width: img.width,
+    height: img.height,
+    data: Buffer.from(img.data.buffer, img.data.byteOffset, img.data.byteLength),
+  };
+}