deprecate GIF in favor of Animation

GIF only adds encode() (encodeGIF), a decode() that accepts nothing but
GIFs (Animation.decode) and its toString. It stays fully working in 3.x,
editors show it as deprecated with the replacement; removal is planned
for 4.0. Frame's documentation now talks about animations instead of GIFs.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Ljnxm1Qjrocq1izGajLx8J

Author: matmen

CHANGELOG.md

@@ -10,6 +10,11 @@
 - **`Animation`**, the base class of `GIF`: an array of frames that decodes GIF and APNG (`Animation.decode()`) and
   encodes `encodeGIF()` and `encodeAPNG()`. `GIF` keeps its API.
 
+### Deprecated
+
+- **`GIF`**: use `Animation`, which works the same and also handles APNG (`new GIF(frames).encode()` becomes
+  `new Animation(frames).encodeGIF()`, `GIF.decode()` becomes `Animation.decode()`). `GIF` will be removed in 4.0.
+
 ## 3.0.0
 
 ImageScript is now written in TypeScript and has no WebAssembly or native binaries anymore. Every codec and renderer

src/frame.ts

@@ -1,44 +1,44 @@
 import { Image, ResizeMode } from './image.ts';
 
-/** Names of the GIF frame disposal modes, see {@link Frame.disposalMode} */
+/** Names of the frame disposal modes, see {@link Frame.disposalMode} */
 export type FrameDisposalModeName = 'any' | 'keep' | 'previous' | 'background';
-/** Ids of the GIF frame disposal modes as stored in the file (0 any, 1 keep, 2 previous, 3 background) */
+/** Ids of the frame disposal modes, as GIFs store them (0 any, 1 keep, 2 previous, 3 background) */
 export type FrameDisposalModeId = 0 | 1 | 2 | 3;
 
 const DISPOSAL_MODES: readonly FrameDisposalModeName[] = ['any', 'keep', 'previous', 'background'];
 
 /**
- * Represents a frame in a GIF
+ * Represents a frame of an {@link Animation}
  */
 export class Frame extends Image {
     /**
-     * Milliseconds. GIFs store hundredths of a second, so this is rounded to 10 ms when encoding;
+     * Milliseconds. GIFs store hundredths of a second, so this is rounded to 10 ms when encoding a GIF;
      * note that browsers play frames shorter than 20 ms with 100 ms
      */
     duration: number;
-    /** The frame's horizontal offset in the GIF */
+    /** The frame's horizontal offset in the animation */
     xOffset: number;
-    /** The frame's vertical offset in the GIF */
+    /** The frame's vertical offset in the animation */
     yOffset: number;
     /** @internal */
     private __disposalMode__: FrameDisposalModeId = 1;
 
-    /** GIF frame disposal mode ANY: the decoder decides (in practice like KEEP). For use with {@link Frame} */
+    /** Frame disposal mode ANY: the decoder decides (in practice like KEEP). For use with {@link Frame} */
     static get DISPOSAL_ANY(): 'any' {
         return 'any';
     }
 
-    /** GIF frame disposal mode KEEP. For use with {@link Frame} */
+    /** Frame disposal mode KEEP. For use with {@link Frame} */
     static get DISPOSAL_KEEP(): 'keep' {
         return 'keep';
     }
 
-    /** GIF frame disposal mode PREVIOUS. For use with {@link Frame} */
+    /** Frame disposal mode PREVIOUS. For use with {@link Frame} */
     static get DISPOSAL_PREVIOUS(): 'previous' {
         return 'previous';
     }
 
-    /** GIF frame disposal mode BACKGROUND. For use with {@link Frame} */
+    /** Frame disposal mode BACKGROUND. For use with {@link Frame} */
     static get DISPOSAL_BACKGROUND(): 'background' {
         return 'background';
     }

src/gif.ts

@@ -6,6 +6,8 @@ import { Animation } from './animation.ts';
 /**
  * Represents a GIF image as an array of frames, an {@link Animation} whose `encode()` and `decode()` work with GIFs.
  * Array methods like map and filter return plain arrays.
+ * @deprecated Use {@link Animation}, which works the same and also handles APNG: `new Animation(frames, loopCount)`,
+ *     {@link Animation.decode} and {@link Animation.encodeGIF}. `GIF` will be removed in 4.0
  */
 export class GIF extends Animation {
     /**
@@ -24,6 +26,7 @@ export class GIF extends Animation {
     /**
      * Encodes the GIF
      * @param quality 1-100, scales the palette size from 8 colors (1) to 256 colors (90 and above)
+     * @deprecated Use {@link Animation.encodeGIF}
      */
     async encode(quality = 95): Promise<Uint8Array> {
         return this.encodeGIF(quality);
@@ -33,6 +36,7 @@ export class GIF extends Animation {
      * Decodes a GIF into fully composited frames
      * @param input The binary data to decode
      * @param onlyExtractFirstFrame Whether to end GIF decoding after the first frame
+     * @deprecated Use {@link Animation.decode}, which decodes APNGs too
      */
     static override async decode(input: BinaryData, onlyExtractFirstFrame = false): Promise<GIF> {
         const data = view(input);

src/index.ts

@@ -16,8 +16,8 @@ export type { ImageTypeName } from './image-type.ts';
 export type { BinaryData } from './util/mem.ts';
 
 /**
- * Decodes any supported image: GIFs are returned as {@link GIF}, everything else (including APNGs, as their default
- * image) as {@link Image}. {@link Animation.decode} decodes the frames of APNGs
+ * Decodes any supported image: GIFs are returned as {@link GIF} (an {@link Animation}), everything else (including
+ * APNGs, as their default image) as {@link Image}. {@link Animation.decode} decodes the frames of GIFs and APNGs
  * @param data The image data
  * @param onlyExtractFirstFrame Whether to end animation decoding after the first frame
  */