pi-simocracy 0.5.0 → 0.5.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-simocracy",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "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)",

package/src/animated-image.ts

@@ -0,0 +1,188 @@
+/**
+ * AnimatedImage — a pi-tui `Component` that cycles through PNG frames in
+ * place using the Kitty graphics protocol's image-by-ID swap.
+ *
+ * Why not just reuse pi-tui's `Image`?
+ *
+ * `Image` caches its render output and `Image.base64Data` is declared
+ * `private`, so we can't mutate the source bytes between renders to
+ * swap frames. Pi-tui's own animated component (`Loader`, the spinner)
+ * works because it extends `Text` and calls `setText()` to swap its
+ * payload — there's no equivalent setter on `Image`. Rather than reach
+ * into pi-tui internals or upstream a patch, we ship a tiny standalone
+ * `Component` that owns its frames + timer and emits the appropriate
+ * Kitty / iTerm2 escape on every `render()` call.
+ *
+ * Behaviour:
+ *
+ *  - `render(width)` always emits the *current* frame's escape sequence
+ *    (no across-frame cache). Same line-shape trick as pi-tui's `Image`:
+ *    return `rows` lines, the last carrying the cursor-up + image
+ *    transmission so the bitmap occupies all `rows` of vertical space.
+ *  - The `setInterval` ticks `currentFrame` and calls
+ *    `tui.requestRender()` — pi-tui re-runs the diff renderer, our
+ *    `render()` produces a new escape, the terminal swaps the bitmap
+ *    in place by image ID. Same pattern pi-tui's spinner uses for the
+ *    text spinner; typing keeps working because input handling is on
+ *    an independent code path.
+ *  - The interval is `unref()`ed so it doesn't keep the node process
+ *    alive on shutdown.
+ *  - `dispose()` clears the interval. Call it when the sim unloads or
+ *    when a new sim takes over the active-animation slot.
+ *  - In terminals without `kitty` / `iterm2` capability the component
+ *    emits a single line of fallback text instead — but in practice
+ *    the message renderer never instantiates `AnimatedImage` on those
+ *    terminals; it returns the ANSI half-block `Text` path.
+ */
+
+import {
+  type Component,
+  type ImageDimensions,
+  type TUI,
+  encodeKitty,
+  encodeITerm2,
+  getCapabilities,
+  calculateImageRows,
+  getCellDimensions,
+} from "@mariozechner/pi-tui";
+
+export interface AnimatedImageOptions {
+  /** Pre-encoded base64 PNG bytes per frame, in playback order.
+   *  At least 2 frames; otherwise just use a static `Image` instead. */
+  frames: string[];
+  /** Native frame dimensions in pixels — used both for aspect ratio
+   *  during display-cell calculation and for the `c=,r=` parameters
+   *  on the Kitty escape. Uniform across all frames. */
+  dimensions: ImageDimensions;
+  /** Display target in terminal cells. Aspect-preserved height is
+   *  computed from `dimensions`. */
+  maxWidthCells: number;
+  /** Stable Kitty image ID — every frame transmission carries this so
+   *  the terminal swaps the bitmap in place rather than stacking
+   *  copies. Allocate once per AnimatedImage with `allocateImageId()`. */
+  imageId: number;
+  /** Display rate. Internally clamped to ≤ 16 fps to keep escape
+   *  bandwidth reasonable. */
+  fps: number;
+  /** TUI handle. Required so we can call `requestRender()` after each
+   *  frame tick. `setWidget`'s factory form is the canonical way to
+   *  obtain this from inside an extension. */
+  tui: TUI;
+  /** Fallback text printed when `getCapabilities().images` is null
+   *  (e.g. user forced ANSI mid-render). Defaults to "[animation]". */
+  fallbackText?: string;
+}
+
+export class AnimatedImage implements Component {
+  private readonly frames: string[];
+  private readonly dimensions: ImageDimensions;
+  private readonly maxWidthCells: number;
+  private readonly imageId: number;
+  private readonly tui: TUI;
+  private readonly fallbackText: string;
+
+  /** Index into `frames`. Mutates on each tick. */
+  private currentFrame = 0;
+  /** Active animation timer, or null when stopped / disposed. */
+  private intervalId: ReturnType<typeof setInterval> | null = null;
+  /** True after `dispose()` — render() then short-circuits to a single
+   *  empty line so the diff renderer cleanly removes the image. */
+  private disposed = false;
+
+  constructor(opts: AnimatedImageOptions) {
+    if (opts.frames.length < 2) {
+      throw new Error(
+        `AnimatedImage requires at least 2 frames (got ${opts.frames.length}); use pi-tui's Image for a single frame.`,
+      );
+    }
+    this.frames = opts.frames;
+    this.dimensions = opts.dimensions;
+    this.maxWidthCells = opts.maxWidthCells;
+    this.imageId = opts.imageId;
+    this.tui = opts.tui;
+    this.fallbackText = opts.fallbackText ?? "[animation]";
+
+    // Clamp fps to ≤ 16 — each tick re-transmits the full PNG, ~30–50
+    // KB per codex pet frame. 16 fps = ~800 KB/s, plenty of headroom.
+    const fps = Math.min(Math.max(opts.fps, 1), 16);
+    const intervalMs = Math.round(1000 / fps);
+    this.intervalId = setInterval(() => {
+      if (this.disposed) return;
+      this.currentFrame = (this.currentFrame + 1) % this.frames.length;
+      // Pi-tui's render tick will call our `render()` again, which
+      // emits the new frame's escape sequence. The terminal swaps the
+      // bitmap in place by image ID — no flicker, no scrollback churn.
+      this.tui.requestRender();
+    }, intervalMs);
+    // Don't keep the node process alive solely for the animation
+    // timer — let SIGINT and process exit work cleanly.
+    this.intervalId.unref?.();
+  }
+
+  /** Stop the timer. Idempotent. After dispose, `render()` returns an
+   *  empty single line so pi-tui's diff renderer cleanly clears the
+   *  cells the animation was occupying. */
+  dispose(): void {
+    if (this.intervalId !== null) {
+      clearInterval(this.intervalId);
+      this.intervalId = null;
+    }
+    this.disposed = true;
+  }
+
+  /**
+   * Emit the current frame as a Kitty / iTerm2 inline image escape.
+   * Same line-shape contract pi-tui's `Image` uses: `rows` lines, the
+   * last one containing `\x1b[<rows-1>A` followed by the actual image
+   * transmission. The first `rows-1` lines are empty; pi-tui's diff
+   * renderer treats them as occupied vertical space.
+   */
+  render(width: number): string[] {
+    if (this.disposed) return [""];
+    const caps = getCapabilities();
+    if (!caps.images) {
+      // Should never happen in practice — the message renderer only
+      // builds an AnimatedImage when caps.images is truthy. Soft
+      // fallback so the layout doesn't collapse if caps change at
+      // runtime (e.g. user resizes into iTerm2 from Kitty mid-session).
+      return [this.fallbackText];
+    }
+    const maxWidth = Math.min(width - 2, this.maxWidthCells);
+    const rows = calculateImageRows(this.dimensions, maxWidth, getCellDimensions());
+    const base64 = this.frames[this.currentFrame] ?? this.frames[0];
+
+    let sequence: string;
+    if (caps.images === "kitty") {
+      // imageId is required for in-place swap — that's the whole point
+      // of AnimatedImage. encodeKitty handles the chunked transmission
+      // for payloads above the protocol's 4096-byte chunk limit.
+      sequence = encodeKitty(base64, {
+        columns: maxWidth,
+        rows,
+        imageId: this.imageId,
+      });
+    } else {
+      // iTerm2: no image-ID swap, but it draws the new image at the
+      // current cursor; combined with the cursor-up trick below, the
+      // visual effect is "in place" enough for our needs.
+      sequence = encodeITerm2(base64, {
+        width: maxWidth,
+        height: "auto",
+        preserveAspectRatio: true,
+      });
+    }
+
+    const lines: string[] = [];
+    for (let i = 0; i < rows - 1; i++) lines.push("");
+    const moveUp = rows > 1 ? `\x1b[${rows - 1}A` : "";
+    lines.push(moveUp + sequence);
+    return lines;
+  }
+
+  /** No internal cache to clear — `render()` always recomputes from
+   *  `currentFrame`. Provided for `Component` interface conformance and
+   *  in case pi-tui ever calls invalidate() on the parent tree. */
+  invalidate(): void {
+    /* intentionally empty */
+  }
+}

package/src/index.ts

@@ -69,6 +69,7 @@ import {
   type ImageTheme,
   type TUI,
 } from "@mariozechner/pi-tui";
+import { AnimatedImage } from "./animated-image.ts";
 import { Type } from "typebox";
 
 import {
@@ -144,9 +145,10 @@ let justUnloaded: string | null = null;
 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. */
+  /** Identifies which loaded-sim message owns this animation. The
+   *  renderer compares against `details.animationKey` to decide
+   *  whether to mount the live `AnimatedImage` for this message or a
+   *  static idle frame. */
   key: string;
   /** Stable Kitty image ID so frame transmissions replace the previous one
    *  instead of stacking. Allocated once per sim load. */
@@ -156,10 +158,17 @@ interface ActiveAnimation {
   /** 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;
+  /** Display rate. */
+  fps: number;
+  /**
+   * The live animated component. Created lazily inside the message
+   * renderer the first time it's asked for this `key` — we need a
+   * TUI handle to construct one, and the renderer is the natural
+   * place that has access (via `capturedTui`). Disposed when a new
+   * sim takes over the active-animation slot or when the sim is
+   * unloaded.
+   */
+  component: AnimatedImage | null;
 }
 let currentAnimation: ActiveAnimation | null = null;
 
@@ -187,15 +196,18 @@ const spriteWidthCells = (() => {
 })();
 
 function stopCurrentAnimation(): void {
-  if (currentAnimation?.intervalId !== null && currentAnimation?.intervalId !== undefined) {
-    clearInterval(currentAnimation.intervalId);
+  if (currentAnimation?.component) {
+    currentAnimation.component.dispose();
   }
   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.
+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 = {
@@ -204,16 +216,12 @@ function startAnimationFor(key: string, frames: { pngBase64: string[]; fps: numb
     frames: frames.pngBase64,
     widthPx: frames.widthPx,
     heightPx: frames.heightPx,
-    currentFrame: 0,
-    intervalId: null,
+    fps: frames.fps,
+    // Lazily instantiated by the message renderer the first time it
+    // sees this `key` — we don't have a TUI handle here, only inside
+    // the setWidget factory.
+    component: 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);
 }
 
 // ---------------------------------------------------------------------------
@@ -668,47 +676,57 @@ export default async function simocracy(pi: ExtensionAPI) {
       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 (
+      const box = new Box(0, 0);
+
+      // If this message owns the active animation slot, mount a live
+      // `AnimatedImage` (cycles frames, owns its own setInterval). We
+      // cache the component on `currentAnimation.component` so we
+      // don't spawn a fresh timer on every re-render of the message
+      // (pi-tui calls the renderer again on expand/collapse, theme
+      // change, etc.).
+      //
+      // For every other case — older loaded-sim messages whose key
+      // doesn't match, sims without animation frames, or animation
+      // disabled via env — we mount a static `Image` of the idle
+      // frame, which freezes gracefully.
+      const isActiveAnimation =
         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 };
+        capturedTui !== null &&
+        details.animationKey !== undefined &&
+        currentAnimation.key === details.animationKey;
+      if (isActiveAnimation) {
+        if (!currentAnimation!.component) {
+          currentAnimation!.component = new AnimatedImage({
+            frames: currentAnimation!.frames,
+            dimensions: {
+              widthPx: currentAnimation!.widthPx,
+              heightPx: currentAnimation!.heightPx,
+            },
+            maxWidthCells: spriteWidthCells,
+            imageId: currentAnimation!.imageId,
+            fps: currentAnimation!.fps,
+            tui: capturedTui!,
+          });
+        }
+        box.addChild(currentAnimation!.component);
+      } else {
+        // 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.
+        box.addChild(
+          new Image(
+            details.spritePngBase64,
+            "image/png",
+            imageTheme,
+            { maxWidthCells: spriteWidthCells },
+            {
+              widthPx: details.spritePngWidth ?? 0,
+              heightPx: details.spritePngHeight ?? 0,
+            },
+          ),
+        );
       }
-      // 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;
     }