onEnd, return values & cancellation

#onEnd

1onEnd?: (2  finalFrameBuffer: Buffer,3  painter: unknown4) => Promise<Buffer | undefined>;

The runtime passes the active ApexPainter instance as the second argument.

finalFrameBuffer is a PNG snapshot of the last fully composited encoder canvas after frame sizing, watermarking, and textOverlay rendering. Use it for a poster/still preview or another derived static result.

onEnd runs only after GIF encoding has finished and the selected primary output has been drained/validated.

#Return values

Without a static onEnd result:

If onEnd returns a Buffer:

• buffer → { gif: Buffer, static: Buffer }
• base64 → { gif: string, static: Buffer }
• attachment → { gif: GIFAttachment[], static: Buffer }
• file → the returned static Buffer only; the GIF remains at outputFile

Unlike the old attachment shortcut, Phase 7 does invoke onEnd for attachment output. Attachment creation drains and validates the encoder output first.

1const result = await painter.createGIF(frames, {2  outputFormat: 'attachment',3  attachmentName: 'preview',4  width: 640,5  height: 360,6  onEnd: async (lastFramePng) => lastFramePng,7});8 9// result.gif[0].name === 'preview.gif'10// result.gif[0].contentType === 'image/gif'11// result.static is the final composited PNG Buffer

#skipResizeWhenDimensionsMatch

Public sizing is always deterministic stretch-to-output.

This is an optimization switch, not a fit/crop mode. Sources whose size differs from the GIF canvas are stretched to options.width × options.height in either case.

#Cancellation (signal)

GIFOptions.signal accepts an AbortSignal.

A cancellation is checked before generated-frame startup and between frame pulls/processing steps, and is forwarded into remote media resolution. On failure/cancellation:

• no additional generated frames are requested;
• encoder/output streams are destroyed where applicable;
• pending output completion is observed to avoid unhandled stream failures;
• a partially written outputFile is removed.

A signal that is already aborted prevents onStart from running.

#Validation recap

Important Phase 7 rules include:

• outputFormat must be file, buffer, base64, or attachment.
• file requires a non-empty outputFile.
• attachmentName, when present, must be a filename rather than a path.
• width and height must be supplied together and fit GIF resource limits.
• repeat allows -1, 0, or a finite positive repeat count within the encoder range.
• quality is an integer from 1 through 30.
• frame/default delays must be finite and within the GIF delay range; zero delay is allowed.
• static frame lists must be non-empty and each frame must provide exactly one source.
• generated arrays/streams cannot exceed configured generated-frame/GIF limits.
• passing both a non-empty static list and onStart is invalid.

Structured Apexify input/resource/network/decode/process errors are used for these failure classes rather than leaking arbitrary backend errors as the public contract.