Introduce avifDiagnostics, which allows for a detailed, freeform error string upon decode error

include/avif/avif.h

diff --git a/include/avif/avif.h b/include/avif/avif.h
index 06eec44..41999de 100644
--- a/include/avif/avif.h
+++ b/include/avif/avif.h
@@ -66,6 +66,8 @@
 #define AVIF_TRUE 1
 #define AVIF_FALSE 0
 
+#define AVIF_DIAGNOSTICS_ERROR_BUFFER_SIZE 256
+
 // a 12 hour AVIF image sequence, running at 60 fps (a basic sanity check as this is quite ridiculous)
 #define AVIF_DEFAULT_IMAGE_COUNT_LIMIT (12 * 3600 * 60)
 
@@ -642,6 +644,18 @@
 AVIF_API void avifIODestroy(avifIO * io);
 
 // ---------------------------------------------------------------------------
+// avifDiagnostics
+
+typedef struct avifDiagnostics
+{
+    // Upon receiving an error from any non-const libavif API call, if the toplevel structure used
+    // in the API call (avifDecoder, avifEncoder) contains a diag member, this buffer may be
+    // populated with a NULL-terminated, freeform error string explaining the most recent error in
+    // more detail. It will be cleared at the beginning of every non-const API call.
+    char error[AVIF_DIAGNOSTICS_ERROR_BUFFER_SIZE];
+} avifDiagnostics;
+
+// ---------------------------------------------------------------------------
 // avifDecoder
 
 // Useful stats related to a read/write
@@ -740,6 +754,9 @@
     // Use one of the avifDecoderSetIO*() functions to set this
     avifIO * io;
 
+    // Additional diagnostics (such as detailed error state)
+    avifDiagnostics diag;
+
     // Internals used by the decoder
     struct avifDecoderData * data;
 } avifDecoder;

include/avif/internal.h

diff --git a/include/avif/internal.h b/include/avif/internal.h
index b068834..c6f23fe 100644
--- a/include/avif/internal.h
+++ b/include/avif/internal.h
@@ -265,6 +265,12 @@
 const char * avifCodecVersionSvt(void);   // requires AVIF_CODEC_SVT (codec_svt.c)
 
 // ---------------------------------------------------------------------------
+// avifDiagnostics
+
+void avifDiagnosticsClearError(avifDiagnostics * diag);
+void avifDiagnosticsPrintf(avifDiagnostics * diag, const char * format, ...);
+
+// ---------------------------------------------------------------------------
 // avifStream
 
 typedef size_t avifBoxMarker;