animate — declarative frame sequences

await painter.animate(frames, defaultDuration, defaultWidth?, defaultHeight?, options?, painterOpts?) renders declarative Frame definitions. It either returns PNG Buffer[] or writes a GIF file through @skyra/gifenc.

This helper is separate from createGIF: it does not expose per-frame GIF disposal/transparency, GIFWatermarkSpec, onStart frame producers, attachment/base64 outputs, or GIF encoder tuning. Use createGIF for the full GIF-specific API.

Implementation: lib-next/gif/animate-frames.ts. Frame lives in types/gif.ts.

#Signature

1animate(2  frames: Frame[],3  defaultDuration: number,4  defaultWidth?: number,   // default 8005  defaultHeight?: number,  // default 6006  options?: AnimateOptions,7  painterOpts?: PainterAssetRefsOptions8): Promise<Buffer[] | undefined>;

frames must be non-empty and stay within central collection/GIF resource limits. Durations are milliseconds and may be zero.

Optional painterOpts.resolveAssetRefs resolves supported $… asset references before animation rendering.

#AnimateOptions

1type AnimateOptions = {2  gif?: boolean;3  gifPath?: string;4  onStart?: () => void;5  onFrame?: (index: number) => void;6  onEnd?: () => void;7  signal?: AbortSignal;8};

When gif: true, gifPath is required.

##Hook order

• onStart fires after validation/cancellation checks and before frame iteration.
• onFrame(i) fires after that frame has been drawn and, in GIF mode, handed to the encoder.
• onEnd fires only after the loop. In GIF mode it runs after encoder.finish(), destination-stream completion, and GIF signature validation.

An already-aborted signal prevents onStart and output allocation. Failures after GIF output begins destroy the stream and remove the partial file.

#Return value and timing behavior

GIF mode resolves only after the output file is complete and its header is verified as GIF87a/GIF89a.

The fixed encoder settings for this convenience path are repeat 0 (loop indefinitely) and quality 10.

#GIF dimensions are fixed

A GIF encoder has one logical screen size, so GIF mode uses exactly defaultWidth × defaultHeight for every frame.

A frame-level width/height override that would differ from those GIF dimensions is rejected. This prevents silent cropping or stale pixels from a previous frame.

Frame-level dimensions remain supported when gif is false, where each PNG frame has its own canvas.

#Rendering order

For each frame:

1. choose frame.width/height or the defaults (non-GIF mode); GIF mode has already required the fixed output size
2. clear the canvas
3. apply optional transform (translate → rotate → scale)
4. resolve background paint:
   • gradient through Apexify's shared gradient renderer (linear, radial, and conic)
   • pattern, when supplied, replaces the gradient fill
   • otherwise backgroundColor
5. draw optional source with blendMode (default source-over)
6. invoke onDrawCustom(ctx, canvas)
7. restore the transform
8. encode the GIF frame or snapshot PNG bytes
9. invoke onFrame
10. non-GIF mode only: apply the requested wall-clock delay

GradientConfig.angle remains supported as the legacy conic-angle alias when startAngle is not provided.

#Media sources use central policy

Frame.source and Frame.pattern.source are strings. Paths, data-image URLs, and allowed remote URLs are resolved through Apexify's shared media layer.

Remote animation sources therefore use the same protocol/host trust policy, SSRF protections, redirect/timeout rules, remote-byte limits, and global remote concurrency controls as other Apexify image workflows. Per-frame animation media is not retained in the shared byte/decode cache solely for reuse inside the sequence.

#Frame reference

#Example — PNG frames

1const pngs = await painter.animate(2  [3    { backgroundColor: '#1e293b' },4    {5      gradient: {6        type: 'conic',7        centerX: 240,8        centerY: 160,9        startAngle: 45,10        colors: [11          { stop: 0, color: '#6366f1' },12          { stop: 0.5, color: '#ec4899' },13          { stop: 1, color: '#6366f1' },14        ],15      },16      duration: 150,17    },18  ],19  120,20  480,21  32022);

#Example — GIF file

1await painter.animate(2  [3    { backgroundColor: '#020617', duration: 180 },4    { backgroundColor: '#0f172a', source: './logo.png', duration: 180 },5  ],6  200,7  640,8  360,9  {10    gif: true,11    gifPath: './out/tick-tock.gif',12    onFrame: (i) => console.log('encoded frame', i),13    onEnd: () => console.log('complete GIF is now on disk'),14  }15);

#Choosing animate vs createGIF