@giveitsmaller/contracts 0.35.0 → 0.37.0

package/availability/availability.json

@@ -1,5 +1,5 @@
 {
-  "capabilities_version": 121,
+  "capabilities_version": 130,
   "endpoints": {
     "DELETE /api/auth/api-keys/{apiKeyId}": {
       "auth": "required",
@@ -1125,7 +1125,7 @@
                 "logic": "or",
                 "width": "set"
               },
-              "description": "Resize mode. max = fit within bounds (preserves aspect ratio, no crop), crop/scale = exact dimensions. Applies only when width or height is set, on whichever Output route runs.",
+              "description": "Resize mode. `max` (default) = fit within bounds, preserving aspect ratio and NEVER upscaling \u2014 it caps at the source dimensions. This IS the \"no-enlarge\" behaviour (there is no separate `no_enlarge` flag \u2014 the worker has no such key). `crop`/`scale` = exact dimensions (`scale` deliberately enlarges past source). Applies only when width or height is set, on whichever Output route runs.",
               "honored_on": [
                 "same_format",
                 "format_change"
@@ -1147,25 +1147,56 @@
               "min": 1,
               "type": "integer"
             },
+            "keep_metadata": {
+              "availability": "planned",
+              "depends_on": {
+                "metadata": "strip"
+              },
+              "description": "Selective per-category metadata keep (optimiser/same_format route): preserve ONLY these categories and strip the rest \u2014 refines the strip path (`metadata: strip`). Valid categories: `copyright`, `gps` (location), `date` (capture time); combinable. `planned` \u2014 the worker does not yet do selective keep (use `metadata: keep` to preserve everything), so the API returns feature_not_available until lambdas proves it.",
+              "honored_on": [
+                "same_format"
+              ],
+              "items": {
+                "type": "string"
+              },
+              "type": "array",
+              "uniqueItems": true
+            },
             "metadata": {
-              "default": "all",
-              "description": "Metadata handling (optimiser/same_format route). `all` = strip all EXIF/IPTC/XMP (default). `keep` = preserve EXIF/ICC/XMP \u2014 STABLE (worker-proven, libcaesium; lambdas PR #260, staging round-trip + unit test). Any other value is rejected as invalid_options.",
+              "default": "strip",
+              "description": "Metadata handling (optimiser/same_format route). `strip` = remove all EXIF/IPTC/XMP (default). `keep` = preserve EXIF/ICC/XMP \u2014 STABLE (worker-proven, libcaesium; lambdas PR #260, staging round-trip + unit test). `all` is a DEPRECATED alias of `strip` (the pre-2026-06-23 token; `all` reading as \"strip all\" was counterintuitive) \u2014 still accepted, emits Deprecation/Sunset, migrate to `strip`. The API lowers `strip`\u2192`all` at the worker boundary. Any other value is rejected as invalid_options.",
               "honored_on": [
                 "same_format"
               ],
+              "per_value_availability": {
+                "all": {
+                  "availability": "deprecated"
+                }
+              },
               "type": "enum",
               "values": [
-                "all",
-                "keep"
+                "strip",
+                "keep",
+                "all"
               ]
             },
             "output_format": {
               "default": "original",
-              "description": "Output format. original = keep input format (default); webp = recompress to WebP \u2014 the one live compress+format target (proven on staging). Other format changes (jpeg/png/avif/gif/tiff) are the convert operation's job, not compress. See FORMAT.md.",
+              "description": "Output format. original = keep input format (default); webp = recompress to WebP \u2014 the one live compress+format target (proven on staging). Concrete format changes (jpeg/png/avif/gif/tiff) are the convert operation's job, not compress. `auto` / `smallest` are PLANNED auto-format directives \u2014 the server encodes to several candidate formats and returns the best (`auto` = the most suitable; `smallest` = the absolute fewest bytes), reporting the chosen format via the result `mime_type`. They are SELECTION STRATEGIES, not concrete targets (convert cannot express \"pick the smallest\"), so they live here and stay `planned` until the API try-all-return-smallest logic + worker proof land. See FORMAT.md.",
+              "per_value_availability": {
+                "auto": {
+                  "availability": "planned"
+                },
+                "smallest": {
+                  "availability": "planned"
+                }
+              },
               "type": "enum",
               "values": [
                 "original",
-                "webp"
+                "webp",
+                "auto",
+                "smallest"
               ]
             },
             "quality": {
@@ -1179,7 +1210,7 @@
               "type": "integer"
             },
             "width": {
-              "description": "Resize-inside-Output: target width in pixels (1-16384; width*height <= max_output_pixels). Resize the image as part of Output (replace semantics, ONE transformed output) using the proven image resize engine (Lanczos, shared with thumbnail-images) \u2014 it is NOT the derivative `thumbnail` op. Optional; omit to keep the source dimensions.",
+              "description": "Resize-inside-Output: target width in pixels (1-16384; width*height <= max_output_pixels). Resize the image as part of Output (replace semantics, ONE transformed output) using the proven convert resize engine (Lanczos; the API routes Output resize through the convert worker, BOTH routes \u2014 the compress optimiser has no resize) \u2014 it is NOT the derivative `thumbnail` op. Optional; omit to keep the source dimensions.",
               "honored_on": [
                 "same_format",
                 "format_change"
@@ -1207,6 +1238,18 @@
               "min": 1,
               "type": "integer"
             },
+            "encoding_mode": {
+              "default": "quality",
+              "description": "Compression mode (mirrors compress.video). `quality` = the `quality` slider drives the encode (default). `target_size` = hit a byte budget via the worker's encode-measure-binary-search loop \u2014 STABLE (worker-proven on staging, lambdas git-870a7c2: re-encode under target + best-effort + original-wins). AVIF encodes are slow, so the loop caps iterations (a 6-iteration cap, ~18s worst case). Optimiser (same_format) route.",
+              "honored_on": [
+                "same_format"
+              ],
+              "type": "enum",
+              "values": [
+                "quality",
+                "target_size"
+              ]
+            },
             "fit": {
               "default": "max",
               "depends_on": {
@@ -1214,7 +1257,7 @@
                 "logic": "or",
                 "width": "set"
               },
-              "description": "Resize mode. max = fit within bounds (preserves aspect ratio, no crop), crop/scale = exact dimensions. Applies only when width or height is set, on whichever Output route runs.",
+              "description": "Resize mode. `max` (default) = fit within bounds, preserving aspect ratio and NEVER upscaling \u2014 it caps at the source dimensions. This IS the \"no-enlarge\" behaviour (there is no separate `no_enlarge` flag \u2014 the worker has no such key). `crop`/`scale` = exact dimensions (`scale` deliberately enlarges past source). Applies only when width or height is set, on whichever Output route runs.",
               "honored_on": [
                 "same_format",
                 "format_change"
@@ -1237,28 +1280,47 @@
               "type": "integer"
             },
             "metadata": {
-              "default": "all",
-              "description": "Metadata handling. `all` = strip all EXIF/IPTC/XMP (the only supported value). `keep` is NOT offered for AVIF \u2014 ravif re-encodes from pixels and cannot preserve metadata (the worker rejects `keep` as invalid_options).",
+              "default": "strip",
+              "description": "Metadata handling. `strip` = remove all EXIF/IPTC/XMP (default, the only supported behaviour). `all` is a DEPRECATED alias of `strip` (migrate to `strip`; the API lowers it at the worker boundary). `keep` is NOT offered for AVIF \u2014 ravif re-encodes from pixels and cannot preserve metadata (the worker rejects `keep` as invalid_options).",
               "honored_on": [
                 "same_format"
               ],
+              "per_value_availability": {
+                "all": {
+                  "availability": "deprecated"
+                }
+              },
               "type": "enum",
               "values": [
+                "strip",
                 "all"
               ]
             },
             "output_format": {
               "default": "original",
-              "description": "Output format. original = keep input format (default); webp = recompress to WebP \u2014 the one live compress+format target (proven on staging). Other format changes (jpeg/png/avif/gif/tiff) are the convert operation's job, not compress. See FORMAT.md.",
+              "description": "Output format. original = keep input format (default); webp = recompress to WebP \u2014 the one live compress+format target (proven on staging). Concrete format changes (jpeg/png/avif/gif/tiff) are the convert operation's job, not compress. `auto` / `smallest` are PLANNED auto-format directives \u2014 the server encodes to several candidate formats and returns the best (`auto` = the most suitable; `smallest` = the absolute fewest bytes), reporting the chosen format via the result `mime_type`. They are SELECTION STRATEGIES, not concrete targets (convert cannot express \"pick the smallest\"), so they live here and stay `planned` until the API try-all-return-smallest logic + worker proof land. See FORMAT.md.",
+              "per_value_availability": {
+                "auto": {
+                  "availability": "planned"
+                },
+                "smallest": {
+                  "availability": "planned"
+                }
+              },
               "type": "enum",
               "values": [
                 "original",
-                "webp"
+                "webp",
+                "auto",
+                "smallest"
               ]
             },
             "quality": {
               "default": 80,
-              "description": "Compression quality (1 = smallest file, 100 = best quality).",
+              "depends_on": {
+                "encoding_mode": "quality"
+              },
+              "description": "Compression quality (1 = smallest file, 100 = best quality). Active in `quality` mode (default); in `target_size` mode the encode-measure loop owns quality, so this option is inactive.",
               "honored_on": [
                 "same_format"
               ],
@@ -1266,8 +1328,19 @@
               "min": 1,
               "type": "integer"
             },
+            "target_size_bytes": {
+              "depends_on": {
+                "encoding_mode": "target_size"
+              },
+              "description": "Target output size in bytes (min 1024 = 1 KiB). The image encode-measure loop binary-searches quality to land at or under the target; best-effort if the target is unreachable at min quality (the result reports the chosen quality + whether the target was met). STABLE (worker-proven, lambdas git-870a7c2). Optimiser (same_format) route.",
+              "honored_on": [
+                "same_format"
+              ],
+              "min": 1024,
+              "type": "integer"
+            },
             "width": {
-              "description": "Resize-inside-Output: target width in pixels (1-16384; width*height <= max_output_pixels). Resize the image as part of Output (replace semantics, ONE transformed output) using the proven image resize engine (Lanczos, shared with thumbnail-images) \u2014 it is NOT the derivative `thumbnail` op. Optional; omit to keep the source dimensions.",
+              "description": "Resize-inside-Output: target width in pixels (1-16384; width*height <= max_output_pixels). Resize the image as part of Output (replace semantics, ONE transformed output) using the proven convert resize engine (Lanczos; the API routes Output resize through the convert worker, BOTH routes \u2014 the compress optimiser has no resize) \u2014 it is NOT the derivative `thumbnail` op. Optional; omit to keep the source dimensions.",
               "honored_on": [
                 "same_format",
                 "format_change"
@@ -1284,6 +1357,30 @@
             "image/jpeg"
           ],
           "options": {
+            "chroma_subsampling": {
+              "description": "JPEG chroma subsampling \u2014 the colour-resolution/size trade-off. `420` (4:2:0) = smallest, chroma at quarter resolution (default-ish for web photos); `422` (4:2:2) = half-horizontal; `444` (4:4:4) = full chroma (largest, best for sharp colour edges / text). JPEG ONLY (declared on image_jpeg only \u2014 ravif hardcodes 4:4:4, libwebp lossy locks 4:2:0). String values (the worker strict-matches strings). STABLE \u2014 worker-proven on staging (lambdas PR #264, deployed git-f2bef85: output JPEG SOF luma sampling bytes verified 0x22/0x21/0x11 for 420/422/444). INCOMPATIBLE with `lossless` (any chroma value): lossless JPEG is a DCT-coefficient copy and cannot resample chroma \u2014 see the chroma_subsampling.lossless_conflict constraint.",
+              "honored_on": [
+                "same_format"
+              ],
+              "type": "enum",
+              "values": [
+                "420",
+                "422",
+                "444"
+              ]
+            },
+            "encoding_mode": {
+              "default": "quality",
+              "description": "Compression mode (mirrors compress.video). `quality` = the `quality` slider drives the encode (default). `target_size` = hit a byte budget via the worker's encode-measure-binary-search loop \u2014 STABLE (worker-proven on staging, lambdas git-870a7c2: re-encode under target + best-effort below floor + original-wins, all proven). Optimiser (same_format) route.",
+              "honored_on": [
+                "same_format"
+              ],
+              "type": "enum",
+              "values": [
+                "quality",
+                "target_size"
+              ]
+            },
             "fit": {
               "default": "max",
               "depends_on": {
@@ -1291,7 +1388,7 @@
                 "logic": "or",
                 "width": "set"
               },
-              "description": "Resize mode. max = fit within bounds (preserves aspect ratio, no crop), crop/scale = exact dimensions. Applies only when width or height is set, on whichever Output route runs.",
+              "description": "Resize mode. `max` (default) = fit within bounds, preserving aspect ratio and NEVER upscaling \u2014 it caps at the source dimensions. This IS the \"no-enlarge\" behaviour (there is no separate `no_enlarge` flag \u2014 the worker has no such key). `crop`/`scale` = exact dimensions (`scale` deliberately enlarges past source). Applies only when width or height is set, on whichever Output route runs.",
               "honored_on": [
                 "same_format",
                 "format_change"
@@ -1313,33 +1410,67 @@
               "min": 1,
               "type": "integer"
             },
+            "keep_metadata": {
+              "availability": "planned",
+              "depends_on": {
+                "metadata": "strip"
+              },
+              "description": "Selective per-category metadata keep (optimiser/same_format route): preserve ONLY these categories and strip the rest \u2014 refines the strip path (`metadata: strip`). Valid categories: `copyright`, `gps` (location), `date` (capture time); combinable. `planned` \u2014 the worker does not yet do selective keep (use `metadata: keep` to preserve everything), so the API returns feature_not_available until lambdas proves it.",
+              "honored_on": [
+                "same_format"
+              ],
+              "items": {
+                "type": "string"
+              },
+              "type": "array",
+              "uniqueItems": true
+            },
             "lossless": {
               "default": false,
-              "description": "Lossless JPEG re-optimisation (optimiser path): optimises the Huffman tables WITHOUT re-encoding pixels \u2014 bit-preserving on the pixel data, no quality loss (it cannot recover detail a lossy JPEG already lost). STABLE \u2014 the compress-image worker honours the `lossless` bool (un-parked 2026-06-23). Optimiser (same_format) route only.",
+              "depends_on": {
+                "encoding_mode": "quality"
+              },
+              "description": "Lossless JPEG re-optimisation (optimiser path): optimises the Huffman tables WITHOUT re-encoding pixels \u2014 bit-preserving on the pixel data, no quality loss (it cannot recover detail a lossy JPEG already lost). STABLE \u2014 the compress-image worker honours the `lossless` bool (un-parked 2026-06-23). Only in `quality` mode \u2014 incompatible with `target_size` (the byte-budget loop is inherently lossy). Optimiser (same_format) route only.",
               "honored_on": [
                 "same_format"
               ],
               "type": "boolean"
             },
             "metadata": {
-              "default": "all",
-              "description": "Metadata handling (optimiser/same_format route). `all` = strip all EXIF/IPTC/XMP (default). `keep` = preserve EXIF/ICC/XMP \u2014 STABLE (worker-proven, libcaesium; lambdas PR #260, staging round-trip + unit test). Any other value is rejected as invalid_options.",
+              "default": "strip",
+              "description": "Metadata handling (optimiser/same_format route). `strip` = remove all EXIF/IPTC/XMP (default). `keep` = preserve EXIF/ICC/XMP \u2014 STABLE (worker-proven, libcaesium; lambdas PR #260, staging round-trip + unit test). `all` is a DEPRECATED alias of `strip` (the pre-2026-06-23 token; `all` reading as \"strip all\" was counterintuitive) \u2014 still accepted, emits Deprecation/Sunset, migrate to `strip`. The API lowers `strip`\u2192`all` at the worker boundary. Any other value is rejected as invalid_options.",
               "honored_on": [
                 "same_format"
               ],
+              "per_value_availability": {
+                "all": {
+                  "availability": "deprecated"
+                }
+              },
               "type": "enum",
               "values": [
-                "all",
-                "keep"
+                "strip",
+                "keep",
+                "all"
               ]
             },
             "output_format": {
               "default": "original",
-              "description": "Output format. original = keep input format (default); webp = recompress to WebP \u2014 the one live compress+format target (proven on staging). Other format changes (jpeg/png/avif/gif/tiff) are the convert operation's job, not compress. See FORMAT.md.",
+              "description": "Output format. original = keep input format (default); webp = recompress to WebP \u2014 the one live compress+format target (proven on staging). Concrete format changes (jpeg/png/avif/gif/tiff) are the convert operation's job, not compress. `auto` / `smallest` are PLANNED auto-format directives \u2014 the server encodes to several candidate formats and returns the best (`auto` = the most suitable; `smallest` = the absolute fewest bytes), reporting the chosen format via the result `mime_type`. They are SELECTION STRATEGIES, not concrete targets (convert cannot express \"pick the smallest\"), so they live here and stay `planned` until the API try-all-return-smallest logic + worker proof land. See FORMAT.md.",
+              "per_value_availability": {
+                "auto": {
+                  "availability": "planned"
+                },
+                "smallest": {
+                  "availability": "planned"
+                }
+              },
               "type": "enum",
               "values": [
                 "original",
-                "webp"
+                "webp",
+                "auto",
+                "smallest"
               ]
             },
             "progressive": {
@@ -1352,7 +1483,10 @@
             },
             "quality": {
               "default": 80,
-              "description": "Compression quality (1 = smallest file, 100 = best quality).",
+              "depends_on": {
+                "encoding_mode": "quality"
+              },
+              "description": "Compression quality (1 = smallest file, 100 = best quality). Active in `quality` mode (default); in `target_size` mode the encode-measure loop owns quality, so this option is inactive.",
               "honored_on": [
                 "same_format"
               ],
@@ -1360,8 +1494,19 @@
               "min": 1,
               "type": "integer"
             },
+            "target_size_bytes": {
+              "depends_on": {
+                "encoding_mode": "target_size"
+              },
+              "description": "Target output size in bytes (min 1024 = 1 KiB). The image encode-measure loop binary-searches quality to land at or under the target; best-effort if the target is unreachable at min quality (the result reports the chosen quality + whether the target was met). STABLE (worker-proven, lambdas git-870a7c2). Optimiser (same_format) route.",
+              "honored_on": [
+                "same_format"
+              ],
+              "min": 1024,
+              "type": "integer"
+            },
             "width": {
-              "description": "Resize-inside-Output: target width in pixels (1-16384; width*height <= max_output_pixels). Resize the image as part of Output (replace semantics, ONE transformed output) using the proven image resize engine (Lanczos, shared with thumbnail-images) \u2014 it is NOT the derivative `thumbnail` op. Optional; omit to keep the source dimensions.",
+              "description": "Resize-inside-Output: target width in pixels (1-16384; width*height <= max_output_pixels). Resize the image as part of Output (replace semantics, ONE transformed output) using the proven convert resize engine (Lanczos; the API routes Output resize through the convert worker, BOTH routes \u2014 the compress optimiser has no resize) \u2014 it is NOT the derivative `thumbnail` op. Optional; omit to keep the source dimensions.",
               "honored_on": [
                 "same_format",
                 "format_change"
@@ -1385,7 +1530,7 @@
                 "logic": "or",
                 "width": "set"
               },
-              "description": "Resize mode. max = fit within bounds (preserves aspect ratio, no crop), crop/scale = exact dimensions. Applies only when width or height is set, on whichever Output route runs.",
+              "description": "Resize mode. `max` (default) = fit within bounds, preserving aspect ratio and NEVER upscaling \u2014 it caps at the source dimensions. This IS the \"no-enlarge\" behaviour (there is no separate `no_enlarge` flag \u2014 the worker has no such key). `crop`/`scale` = exact dimensions (`scale` deliberately enlarges past source). Applies only when width or height is set, on whichever Output route runs.",
               "honored_on": [
                 "same_format",
                 "format_change"
@@ -1407,6 +1552,21 @@
               "min": 1,
               "type": "integer"
             },
+            "keep_metadata": {
+              "availability": "planned",
+              "depends_on": {
+                "metadata": "strip"
+              },
+              "description": "Selective per-category metadata keep (optimiser/same_format route): preserve ONLY these categories and strip the rest \u2014 refines the strip path (`metadata: strip`). Valid categories: `copyright`, `gps` (location), `date` (capture time); combinable. `planned` \u2014 the worker does not yet do selective keep (use `metadata: keep` to preserve everything), so the API returns feature_not_available until lambdas proves it.",
+              "honored_on": [
+                "same_format"
+              ],
+              "items": {
+                "type": "string"
+              },
+              "type": "array",
+              "uniqueItems": true
+            },
             "lossy": {
               "availability": "planned",
               "default": false,
@@ -1417,15 +1577,21 @@
               "type": "boolean"
             },
             "metadata": {
-              "default": "all",
-              "description": "Metadata handling (optimiser/same_format route). `all` = strip all EXIF/IPTC/XMP (default). `keep` = preserve EXIF/ICC/XMP \u2014 STABLE (worker-proven, libcaesium; lambdas PR #260, staging round-trip + unit test). Any other value is rejected as invalid_options.",
+              "default": "strip",
+              "description": "Metadata handling (optimiser/same_format route). `strip` = remove all EXIF/IPTC/XMP (default). `keep` = preserve EXIF/ICC/XMP \u2014 STABLE (worker-proven, libcaesium; lambdas PR #260, staging round-trip + unit test). `all` is a DEPRECATED alias of `strip` (the pre-2026-06-23 token; `all` reading as \"strip all\" was counterintuitive) \u2014 still accepted, emits Deprecation/Sunset, migrate to `strip`. The API lowers `strip`\u2192`all` at the worker boundary. Any other value is rejected as invalid_options.",
               "honored_on": [
                 "same_format"
               ],
+              "per_value_availability": {
+                "all": {
+                  "availability": "deprecated"
+                }
+              },
               "type": "enum",
               "values": [
-                "all",
-                "keep"
+                "strip",
+                "keep",
+                "all"
               ]
             },
             "optimization_level": {
@@ -1440,11 +1606,21 @@
             },
             "output_format": {
               "default": "original",
-              "description": "Output format. original = keep input format (default); webp = recompress to WebP \u2014 the one live compress+format target (proven on staging). Other format changes (jpeg/png/avif/gif/tiff) are the convert operation's job, not compress. See FORMAT.md.",
+              "description": "Output format. original = keep input format (default); webp = recompress to WebP \u2014 the one live compress+format target (proven on staging). Concrete format changes (jpeg/png/avif/gif/tiff) are the convert operation's job, not compress. `auto` / `smallest` are PLANNED auto-format directives \u2014 the server encodes to several candidate formats and returns the best (`auto` = the most suitable; `smallest` = the absolute fewest bytes), reporting the chosen format via the result `mime_type`. They are SELECTION STRATEGIES, not concrete targets (convert cannot express \"pick the smallest\"), so they live here and stay `planned` until the API try-all-return-smallest logic + worker proof land. See FORMAT.md.",
+              "per_value_availability": {
+                "auto": {
+                  "availability": "planned"
+                },
+                "smallest": {
+                  "availability": "planned"
+                }
+              },
               "type": "enum",
               "values": [
                 "original",
-                "webp"
+                "webp",
+                "auto",
+                "smallest"
               ]
             },
             "quality": {
@@ -1458,7 +1634,7 @@
               "type": "integer"
             },
             "width": {
-              "description": "Resize-inside-Output: target width in pixels (1-16384; width*height <= max_output_pixels). Resize the image as part of Output (replace semantics, ONE transformed output) using the proven image resize engine (Lanczos, shared with thumbnail-images) \u2014 it is NOT the derivative `thumbnail` op. Optional; omit to keep the source dimensions.",
+              "description": "Resize-inside-Output: target width in pixels (1-16384; width*height <= max_output_pixels). Resize the image as part of Output (replace semantics, ONE transformed output) using the proven convert resize engine (Lanczos; the API routes Output resize through the convert worker, BOTH routes \u2014 the compress optimiser has no resize) \u2014 it is NOT the derivative `thumbnail` op. Optional; omit to keep the source dimensions.",
               "honored_on": [
                 "same_format",
                 "format_change"
@@ -1475,23 +1651,39 @@
           ],
           "options": {
             "metadata": {
-              "default": "all",
-              "description": "Metadata handling. `all` = strip all metadata (the only supported value). `keep` is NOT offered for SVG \u2014 SVGO optimises the markup and cannot preserve a metadata block (the worker rejects `keep` as invalid_options).",
+              "default": "strip",
+              "description": "Metadata handling. `strip` = remove all metadata (default, the only supported behaviour). `all` is a DEPRECATED alias of `strip` (migrate to `strip`; the API lowers it at the worker boundary). `keep` is NOT offered for SVG \u2014 SVGO optimises the markup and cannot preserve a metadata block (the worker rejects `keep` as invalid_options).",
               "honored_on": [
                 "same_format"
               ],
+              "per_value_availability": {
+                "all": {
+                  "availability": "deprecated"
+                }
+              },
               "type": "enum",
               "values": [
+                "strip",
                 "all"
               ]
             },
             "output_format": {
               "default": "original",
-              "description": "Output format. original = keep input format (default); webp = recompress to WebP. Other format changes are the convert operation's job. See FORMAT.md.",
+              "description": "Output format. original = keep input format (default); webp = recompress to WebP. Concrete format changes are the convert operation's job. `auto` / `smallest` are PLANNED auto-format directives (server picks the best/smallest candidate format, reported via the result `mime_type`) \u2014 selection strategies, not concrete targets, planned until the API logic + worker proof land. See FORMAT.md.",
+              "per_value_availability": {
+                "auto": {
+                  "availability": "planned"
+                },
+                "smallest": {
+                  "availability": "planned"
+                }
+              },
               "type": "enum",
               "values": [
                 "original",
-                "webp"
+                "webp",
+                "auto",
+                "smallest"
               ]
             },
             "quality": {
@@ -1512,6 +1704,18 @@
             "image/webp"
           ],
           "options": {
+            "encoding_mode": {
+              "default": "quality",
+              "description": "Compression mode (mirrors compress.video). `quality` = the `quality` slider drives the encode (default). `target_size` = hit a byte budget via the worker's encode-measure-binary-search loop \u2014 STABLE (worker-proven on staging, lambdas git-870a7c2: re-encode under target + best-effort below floor + original-wins, all proven). Optimiser (same_format) route.",
+              "honored_on": [
+                "same_format"
+              ],
+              "type": "enum",
+              "values": [
+                "quality",
+                "target_size"
+              ]
+            },
             "fit": {
               "default": "max",
               "depends_on": {
@@ -1519,7 +1723,7 @@
                 "logic": "or",
                 "width": "set"
               },
-              "description": "Resize mode. max = fit within bounds (preserves aspect ratio, no crop), crop/scale = exact dimensions. Applies only when width or height is set, on whichever Output route runs.",
+              "description": "Resize mode. `max` (default) = fit within bounds, preserving aspect ratio and NEVER upscaling \u2014 it caps at the source dimensions. This IS the \"no-enlarge\" behaviour (there is no separate `no_enlarge` flag \u2014 the worker has no such key). `crop`/`scale` = exact dimensions (`scale` deliberately enlarges past source). Applies only when width or height is set, on whichever Output route runs.",
               "honored_on": [
                 "same_format",
                 "format_change"
@@ -1541,38 +1745,75 @@
               "min": 1,
               "type": "integer"
             },
+            "keep_metadata": {
+              "availability": "planned",
+              "depends_on": {
+                "metadata": "strip"
+              },
+              "description": "Selective per-category metadata keep (optimiser/same_format route): preserve ONLY these categories and strip the rest \u2014 refines the strip path (`metadata: strip`). Valid categories: `copyright`, `gps` (location), `date` (capture time); combinable. `planned` \u2014 the worker does not yet do selective keep (use `metadata: keep` to preserve everything), so the API returns feature_not_available until lambdas proves it.",
+              "honored_on": [
+                "same_format"
+              ],
+              "items": {
+                "type": "string"
+              },
+              "type": "array",
+              "uniqueItems": true
+            },
             "lossless": {
               "default": false,
-              "description": "Encode WebP losslessly (optimiser path): a genuine lossless WebP encode. STABLE \u2014 the compress-image worker honours the `lossless` bool (un-parked 2026-06-23). Note a lossless encode can be LARGER than a lossy one at the same visual quality. Optimiser (same_format) route only.",
+              "depends_on": {
+                "encoding_mode": "quality"
+              },
+              "description": "Encode WebP losslessly (optimiser path): a genuine lossless WebP encode. STABLE \u2014 the compress-image worker honours the `lossless` bool (un-parked 2026-06-23). Note a lossless encode can be LARGER than a lossy one at the same visual quality. Only in `quality` mode \u2014 incompatible with `target_size` (the byte-budget loop is inherently lossy). Optimiser (same_format) route only.",
               "honored_on": [
                 "same_format"
               ],
               "type": "boolean"
             },
             "metadata": {
-              "default": "all",
-              "description": "Metadata handling (optimiser/same_format route). `all` = strip all EXIF/IPTC/XMP (default). `keep` = preserve EXIF/ICC/XMP \u2014 STABLE (worker-proven, libcaesium; lambdas PR #260, staging round-trip + unit test). Any other value is rejected as invalid_options.",
+              "default": "strip",
+              "description": "Metadata handling (optimiser/same_format route). `strip` = remove all EXIF/IPTC/XMP (default). `keep` = preserve EXIF/ICC/XMP \u2014 STABLE (worker-proven, libcaesium; lambdas PR #260, staging round-trip + unit test). `all` is a DEPRECATED alias of `strip` (the pre-2026-06-23 token; `all` reading as \"strip all\" was counterintuitive) \u2014 still accepted, emits Deprecation/Sunset, migrate to `strip`. The API lowers `strip`\u2192`all` at the worker boundary. Any other value is rejected as invalid_options.",
               "honored_on": [
                 "same_format"
               ],
+              "per_value_availability": {
+                "all": {
+                  "availability": "deprecated"
+                }
+              },
               "type": "enum",
               "values": [
-                "all",
-                "keep"
+                "strip",
+                "keep",
+                "all"
               ]
             },
             "output_format": {
               "default": "original",
-              "description": "Output format. original = keep input format (default); webp = recompress to WebP \u2014 the one live compress+format target (proven on staging). Other format changes (jpeg/png/avif/gif/tiff) are the convert operation's job, not compress. See FORMAT.md.",
+              "description": "Output format. original = keep input format (default); webp = recompress to WebP \u2014 the one live compress+format target (proven on staging). Concrete format changes (jpeg/png/avif/gif/tiff) are the convert operation's job, not compress. `auto` / `smallest` are PLANNED auto-format directives \u2014 the server encodes to several candidate formats and returns the best (`auto` = the most suitable; `smallest` = the absolute fewest bytes), reporting the chosen format via the result `mime_type`. They are SELECTION STRATEGIES, not concrete targets (convert cannot express \"pick the smallest\"), so they live here and stay `planned` until the API try-all-return-smallest logic + worker proof land. See FORMAT.md.",
+              "per_value_availability": {
+                "auto": {
+                  "availability": "planned"
+                },
+                "smallest": {
+                  "availability": "planned"
+                }
+              },
               "type": "enum",
               "values": [
                 "original",
-                "webp"
+                "webp",
+                "auto",
+                "smallest"
               ]
             },
             "quality": {
               "default": 80,
-              "description": "Compression quality (1 = smallest file, 100 = best quality).",
+              "depends_on": {
+                "encoding_mode": "quality"
+              },
+              "description": "Compression quality (1 = smallest file, 100 = best quality). Active in `quality` mode (default); in `target_size` mode the encode-measure loop owns quality, so this option is inactive.",
               "honored_on": [
                 "same_format"
               ],
@@ -1580,8 +1821,19 @@
               "min": 1,
               "type": "integer"
             },
+            "target_size_bytes": {
+              "depends_on": {
+                "encoding_mode": "target_size"
+              },
+              "description": "Target output size in bytes (min 1024 = 1 KiB). The image encode-measure loop binary-searches quality to land at or under the target; best-effort if the target is unreachable at min quality (the result reports the chosen quality + whether the target was met). STABLE (worker-proven, lambdas git-870a7c2). Optimiser (same_format) route.",
+              "honored_on": [
+                "same_format"
+              ],
+              "min": 1024,
+              "type": "integer"
+            },
             "width": {
-              "description": "Resize-inside-Output: target width in pixels (1-16384; width*height <= max_output_pixels). Resize the image as part of Output (replace semantics, ONE transformed output) using the proven image resize engine (Lanczos, shared with thumbnail-images) \u2014 it is NOT the derivative `thumbnail` op. Optional; omit to keep the source dimensions.",
+              "description": "Resize-inside-Output: target width in pixels (1-16384; width*height <= max_output_pixels). Resize the image as part of Output (replace semantics, ONE transformed output) using the proven convert resize engine (Lanczos; the API routes Output resize through the convert worker, BOTH routes \u2014 the compress optimiser has no resize) \u2014 it is NOT the derivative `thumbnail` op. Optional; omit to keep the source dimensions.",
               "honored_on": [
                 "same_format",
                 "format_change"
@@ -1865,12 +2117,11 @@
           }
         },
         "image": {
+          "max_output_pixels": 16000000,
           "mimes": [
             "image/jpeg",
             "image/png",
-            "image/gif",
             "image/webp",
-            "image/svg+xml",
             "image/tiff",
             "image/bmp",
             "image/vnd.microsoft.icon",
@@ -1889,6 +2140,46 @@
               "pattern": "^#[0-9a-fA-F]{6}$",
               "type": "string"
             },
+            "fit": {
+              "default": "max",
+              "depends_on": {
+                "height": "set",
+                "logic": "or",
+                "width": "set"
+              },
+              "description": "Resize mode. `max` (default) = fit within bounds, preserving aspect ratio and NEVER upscaling \u2014 it caps at the source dimensions. This IS the \"no-enlarge\" behaviour (there is no separate `no_enlarge` flag \u2014 the worker has no such key). `crop`/`scale` = exact dimensions (`scale` deliberately enlarges past source). Applies only when width or height is set.",
+              "honored_on": [
+                "format_change"
+              ],
+              "type": "enum",
+              "values": [
+                "max",
+                "crop",
+                "scale"
+              ]
+            },
+            "height": {
+              "description": "Resize-inside-Output: target height in pixels (1-16384; width*height <= max_output_pixels). Not honored for SVG input. See `width`.",
+              "honored_on": [
+                "format_change"
+              ],
+              "max": 16384,
+              "min": 1,
+              "type": "integer"
+            },
+            "metadata": {
+              "availability": "planned",
+              "default": "strip",
+              "description": "Metadata handling on the format-change (convert/transcoder) route. `strip` = remove all EXIF/IPTC/XMP (default), `keep` = preserve. `planned` \u2014 the convert worker re-encodes from pixels and does not yet preserve metadata across a format change, so the API returns feature_not_available (rather than \"Unknown option\" on a format-change request \u2014 e2e/api flagged 2026-06-23). This is a new (planned) surface, so it carries no deprecated `all` alias \u2014 unlike compress.image.metadata, which keeps `all` for its existing callers. Stable-flip gated on lambdas proving convert-route metadata preservation; the honoured target subset may narrow (avif/heic targets re-encode and cannot keep).",
+              "honored_on": [
+                "format_change"
+              ],
+              "type": "enum",
+              "values": [
+                "strip",
+                "keep"
+              ]
+            },
             "output_format": {
               "description": "Target format",
               "required": true,
@@ -1918,6 +2209,15 @@
               "max": 100,
               "min": 1,
               "type": "integer"
+            },
+            "width": {
+              "description": "Resize-inside-Output: target width in pixels (1-16384; width*height <= max_output_pixels). The convert worker resizes (Lanczos) before encode; single transformed output. NOT honored for SVG input (the worker rejects svg resize). Input-gated \u2014 see the resize comment above.",
+              "honored_on": [
+                "format_change"
+              ],
+              "max": 16384,
+              "min": 1,
+              "type": "integer"
             }
           },
           "per_mime_availability": {
@@ -1929,6 +2229,162 @@
             }
           }
         },
+        "image_gif": {
+          "max_output_pixels": 16000000,
+          "mimes": [
+            "image/gif"
+          ],
+          "options": {
+            "background": {
+              "depends_on": {
+                "output_format": "jpeg"
+              },
+              "description": "Background colour as a 6-digit hex (`#RRGGBB`) for a transparent GIF flattened to JPEG (alpha-flatten). HEX ONLY \u2014 non-hex is rejected as `invalid_options` (see convert.image.background).",
+              "honored_on": [
+                "format_change"
+              ],
+              "pattern": "^#[0-9a-fA-F]{6}$",
+              "type": "string"
+            },
+            "fit": {
+              "default": "max",
+              "depends_on": {
+                "height": "set",
+                "logic": "or",
+                "width": "set"
+              },
+              "description": "Resize mode. `max` (default) = fit within bounds, preserving aspect ratio and never upscaling; `crop`/`scale` = exact dimensions. Applies only when width or height is set.",
+              "honored_on": [
+                "format_change"
+              ],
+              "type": "enum",
+              "values": [
+                "max",
+                "crop",
+                "scale"
+              ]
+            },
+            "height": {
+              "description": "Resize-inside-Output: target height in pixels (1-16384; width*height <= max_output_pixels). See `width`.",
+              "honored_on": [
+                "format_change"
+              ],
+              "max": 16384,
+              "min": 1,
+              "type": "integer"
+            },
+            "metadata": {
+              "availability": "planned",
+              "default": "strip",
+              "description": "Metadata handling on the format-change route (still-image targets). `planned` \u2014 mirrors convert.image.metadata (the convert worker does not yet preserve metadata across a format change). The video targets carry no EXIF/IPTC/XMP.",
+              "honored_on": [
+                "format_change"
+              ],
+              "type": "enum",
+              "values": [
+                "strip",
+                "keep"
+              ]
+            },
+            "output_format": {
+              "description": "Target format. The still-image targets (jpeg/png/webp/avif/gif/tiff) take the first frame / rasterise (stable, today's gif-convert behaviour). `mp4` / `webm` are the NEW (planned) GIF\u2192VIDEO transcode targets \u2014 the animated GIF becomes a muted, play-once video (`mp4` = H.264 / yuv420p / +faststart, plays everywhere; `webm` = VP9, smaller). GIFs are silent (no audio stream); the GIF infinite-loop becomes a playback attribute (`<video loop>`) the player sets, NOT baked into the file. mp4 and webm flip planned\u2192stable independently on worker proof.",
+              "per_value_availability": {
+                "mp4": {
+                  "availability": "planned"
+                },
+                "webm": {
+                  "availability": "planned"
+                }
+              },
+              "required": true,
+              "type": "enum",
+              "values": [
+                "jpeg",
+                "png",
+                "webp",
+                "avif",
+                "gif",
+                "tiff",
+                "mp4",
+                "webm"
+              ]
+            },
+            "quality": {
+              "default": 85,
+              "depends_on": {
+                "output_format": [
+                  "jpeg",
+                  "webp",
+                  "avif"
+                ]
+              },
+              "description": "Output quality for the lossy STILL-IMAGE targets (jpeg/webp/avif). The video targets (mp4/webm) use a sensible default encode quality in v1 \u2014 there is no exposed CRF knob yet (planned-first; may be added later).",
+              "honored_on": [
+                "format_change"
+              ],
+              "max": 100,
+              "min": 1,
+              "type": "integer"
+            },
+            "width": {
+              "description": "Resize-inside-Output: target width in pixels (1-16384; width*height <= max_output_pixels). Applies to the still-image targets; for the planned mp4/webm video targets, resize applicability is settled at the worker flip.",
+              "honored_on": [
+                "format_change"
+              ],
+              "max": 16384,
+              "min": 1,
+              "type": "integer"
+            }
+          }
+        },
+        "image_svg": {
+          "mimes": [
+            "image/svg+xml"
+          ],
+          "options": {
+            "background": {
+              "depends_on": {
+                "output_format": "jpeg"
+              },
+              "description": "Background colour as a 6-digit hex (`#RRGGBB`) for transparent SVG rasterised to JPEG (alpha-flatten). HEX ONLY \u2014 non-hex is rejected as `invalid_options` (see convert.image.background).",
+              "honored_on": [
+                "format_change"
+              ],
+              "pattern": "^#[0-9a-fA-F]{6}$",
+              "type": "string"
+            },
+            "output_format": {
+              "description": "Target raster format (SVG is rasterised, then encoded).",
+              "required": true,
+              "type": "enum",
+              "values": [
+                "jpeg",
+                "png",
+                "webp",
+                "avif",
+                "gif",
+                "tiff"
+              ]
+            },
+            "quality": {
+              "default": 85,
+              "depends_on": {
+                "output_format": [
+                  "jpeg",
+                  "webp",
+                  "avif"
+                ]
+              },
+              "description": "Output quality for lossy formats",
+              "honored_on": [
+                "format_change"
+              ],
+              "max": 100,
+              "min": 1,
+              "type": "integer"
+            }
+          }
+        },
         "video": {
           "mimes": [
             "video/mp4",
@@ -3941,7 +4397,7 @@
       "sole_op": true
     }
   },
-  "schema_version": "2.102.0",
+  "schema_version": "2.111.0",
   "source_commit": null,
   "user_tier": null,
   "workflow_features": {