npm - @giveitsmaller/contracts - Versions diffs - 0.48.0 → 0.51.0 - Mend

@giveitsmaller/contracts 0.48.0 → 0.51.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (488) hide show

package/availability/availability.json CHANGED Viewed

@@ -1,5 +1,5 @@
 {
-  "capabilities_version": 147,
+  "capabilities_version": 162,
   "endpoints": {
     "DELETE /api/auth/api-keys/{apiKeyId}": {
       "auth": "required",
@@ -169,6 +169,13 @@
       "operation_id": "verifyEmail",
       "required_tier": null
     },
+    "POST /api/billing/checkout": {
+      "auth": "required",
+      "availability": "stable",
+      "identity_scoped": true,
+      "operation_id": "createBillingCheckoutSession",
+      "required_tier": null
+    },
     "POST /api/contact": {
       "auth": "anonymous",
       "availability": "stable",
@@ -960,14 +967,6 @@
               "description": "Subset embedded fonts to only include glyphs used in the document. Significant size reduction for books with large font files. `planned` \u2014 not yet supported.",
               "type": "boolean"
             },
-            "image_quality": {
-              "availability": "planned",
-              "default": 80,
-              "description": "Recompress embedded images at this quality level. `planned` \u2014 not yet supported (use `quality`).",
-              "max": 100,
-              "min": 1,
-              "type": "integer"
-            },
             "quality": {
               "default": 50,
               "description": "Compression quality (1 = smallest, 100 = best). The only document compression option supported today.",
@@ -990,14 +989,6 @@
             "application/vnd.oasis.opendocument.presentation"
           ],
           "options": {
-            "image_quality": {
-              "availability": "planned",
-              "default": 80,
-              "description": "Recompress embedded images at this quality level. `planned` \u2014 not yet supported (use `quality`).",
-              "max": 100,
-              "min": 1,
-              "type": "integer"
-            },
             "quality": {
               "default": 50,
               "description": "Compression quality (1 = smallest, 100 = best). The only document compression option supported today.",
@@ -1026,14 +1017,6 @@
             "application/vnd.openxmlformats-officedocument.presentationml.presentation"
           ],
           "options": {
-            "image_quality": {
-              "availability": "planned",
-              "default": 80,
-              "description": "Recompress embedded images at this quality level (1 = smallest, 100 = best). `planned` \u2014 not yet supported (use `quality`).",
-              "max": 100,
-              "min": 1,
-              "type": "integer"
-            },
             "quality": {
               "default": 50,
               "description": "Compression quality (1 = smallest, 100 = best). The only document compression option supported today.",
@@ -1183,26 +1166,6 @@
               "min": 1,
               "type": "integer"
             },
-            "keep_metadata": {
-              "availability": "planned",
-              "depends_on": {
-                "metadata": "strip"
-              },
-              "description": "Selectively keep only certain metadata categories and strip the rest \u2014 refines `metadata: strip`. Allowed categories: `copyright`, `gps` (location), `date` (capture time); combinable. `planned` \u2014 selective keep is not yet supported (use `metadata: keep` to preserve everything).",
-              "honored_on": [
-                "same_format"
-              ],
-              "items": {
-                "enum": [
-                  "copyright",
-                  "gps",
-                  "date"
-                ],
-                "type": "string"
-              },
-              "type": "array",
-              "uniqueItems": true
-            },
             "metadata": {
               "default": "strip",
               "description": "Metadata handling. `strip` = remove all EXIF/IPTC/XMP (default). `keep` = preserve EXIF, colour profile, and XMP. `all` is a DEPRECATED alias of `strip` (kept for older callers; emits Deprecation/Sunset headers \u2014 migrate to `strip`). Any other value is rejected.",
@@ -1263,7 +1226,6 @@
           }
         },
         "image_avif": {
-          "availability": "beta",
           "max_output_pixels": 16000000,
           "mimes": [
             "image/avif"
@@ -1289,9 +1251,8 @@
               "type": "integer"
             },
             "color_profile": {
-              "availability": "planned",
               "default": "keep",
-              "description": "Colour-profile handling \u2014 a dedicated control, separate from `metadata` so that stripping metadata never silently shifts colours. `keep` (default) = preserve the embedded colour profile; `srgb` = convert to sRGB (also handles CMYK \u2192 sRGB); `strip` = drop the profile (smallest \u2014 only when the consumer manages colour itself). `planned` \u2014 not yet supported.",
+              "description": "Colour-profile handling \u2014 a dedicated control, separate from `metadata` so that stripping metadata never silently shifts colours. `keep` (default) = preserve your colours: embed the ICC profile where the output format can carry one, otherwise convert to sRGB and bake the colours in so they survive (never a silent drop \u2014 for AVIF the gamut is baked to sRGB); `srgb` = convert to sRGB (transform pixels to sRGB, emit untagged \u2014 no embedded ICC, the web default; CMYK/grayscale best-effort); `strip` = drop the profile (smallest \u2014 only when the consumer manages colour itself). All three values are live on compress AVIF \u2014 `srgb` flipped planned->stable 2026-06-30 on the lambdas proof (wide-gamut-p3-icc.avif: srgb bakes untagged, whole-image RMSE 0.041 / 92% pixels shifted vs strip). Note: on AVIF `keep` and `srgb` both bake the gamut to sRGB by design, so keep_px == srgb_px; the proving inequality is srgb != strip, which holds.",
               "honored_on": [
                 "same_format",
                 "format_change"
@@ -1305,14 +1266,15 @@
             },
             "encoding_mode": {
               "default": "quality",
-              "description": "Compression mode. `quality` = the `quality` slider drives the encode (default). `target_size` = automatically find the highest quality that fits a byte budget (set via `target_size_bytes`); if the budget can't be met even at the lowest quality, the closest result is returned, and the original is kept if re-encoding wouldn't be smaller. AVIF encoding is slower, so the search is bounded and may stop slightly above the budget.",
+              "description": "Compression mode. `quality` = the `quality` slider drives the encode (default). `target_size` = automatically find the highest quality that fits a byte budget (set via `target_size_bytes`); if the budget can't be met even at the lowest quality, the closest result is returned, and the original is kept if re-encoding wouldn't be smaller. `auto_quality` = hit a named perceptual-quality target (set via `quality_preset`) and let the worker pick the encoder quality that meets it \u2014 the perceptual twin of `target_size` (which targets bytes); the result reports the chosen quality. AVIF encoding is slower, so the search is bounded and may stop slightly above the budget.",
               "honored_on": [
                 "same_format"
               ],
               "type": "enum",
               "values": [
                 "quality",
-                "target_size"
+                "target_size",
+                "auto_quality"
               ]
             },
             "fit": {
@@ -1393,6 +1355,23 @@
               "min": 1,
               "type": "integer"
             },
+            "quality_preset": {
+              "default": "good",
+              "depends_on": {
+                "encoding_mode": "auto_quality"
+              },
+              "description": "Named perceptual-quality target for `encoding_mode: auto_quality` (best > good > fair > low; `good` is the default). The worker runs a perceptual-target search and picks the encoder quality that meets the named tier \u2014 the wire carries the NAME only, so the tier\u2192target mapping stays worker-internal and calibration-tunable without a contract change. Requires `encoding_mode: auto_quality`. The achieved perceptual score is reported on the result as `metrics.measured_quality` (+ `metrics.quality_metric`).",
+              "honored_on": [
+                "same_format"
+              ],
+              "type": "enum",
+              "values": [
+                "best",
+                "good",
+                "fair",
+                "low"
+              ]
+            },
             "target_size_bytes": {
               "depends_on": {
                 "encoding_mode": "target_size"
@@ -1459,14 +1438,15 @@
             },
             "encoding_mode": {
               "default": "quality",
-              "description": "Compression mode. `quality` = the `quality` slider drives the encode (default). `target_size` = automatically find the highest quality that fits a byte budget (set via `target_size_bytes`); if the budget can't be met even at the lowest quality, the closest result is returned, and the original is kept if re-encoding wouldn't be smaller.",
+              "description": "Compression mode. `quality` = the `quality` slider drives the encode (default). `target_size` = automatically find the highest quality that fits a byte budget (set via `target_size_bytes`); if the budget can't be met even at the lowest quality, the closest result is returned, and the original is kept if re-encoding wouldn't be smaller. `auto_quality` = hit a named perceptual-quality target (set via `quality_preset`) and let the worker pick the encoder quality that meets it \u2014 the perceptual twin of `target_size` (which targets bytes); the result reports the chosen quality.",
               "honored_on": [
                 "same_format"
               ],
               "type": "enum",
               "values": [
                 "quality",
-                "target_size"
+                "target_size",
+                "auto_quality"
               ]
             },
             "fit": {
@@ -1498,26 +1478,6 @@
               "min": 1,
               "type": "integer"
             },
-            "keep_metadata": {
-              "availability": "planned",
-              "depends_on": {
-                "metadata": "strip"
-              },
-              "description": "Selectively keep only certain metadata categories and strip the rest \u2014 refines `metadata: strip`. Allowed categories: `copyright`, `gps` (location), `date` (capture time); combinable. `planned` \u2014 selective keep is not yet supported (use `metadata: keep` to preserve everything).",
-              "honored_on": [
-                "same_format"
-              ],
-              "items": {
-                "enum": [
-                  "copyright",
-                  "gps",
-                  "date"
-                ],
-                "type": "string"
-              },
-              "type": "array",
-              "uniqueItems": true
-            },
             "lossless": {
               "default": false,
               "depends_on": {
@@ -1587,6 +1547,23 @@
               "min": 1,
               "type": "integer"
             },
+            "quality_preset": {
+              "default": "good",
+              "depends_on": {
+                "encoding_mode": "auto_quality"
+              },
+              "description": "Named perceptual-quality target for `encoding_mode: auto_quality` (best > good > fair > low; `good` is the default). The worker runs a perceptual-target search and picks the encoder quality that meets the named tier \u2014 the wire carries the NAME only, so the tier\u2192target mapping stays worker-internal and calibration-tunable without a contract change. Requires `encoding_mode: auto_quality`. The achieved perceptual score is reported on the result as `metrics.measured_quality` (+ `metrics.quality_metric`).",
+              "honored_on": [
+                "same_format"
+              ],
+              "type": "enum",
+              "values": [
+                "best",
+                "good",
+                "fair",
+                "low"
+              ]
+            },
             "target_size_bytes": {
               "depends_on": {
                 "encoding_mode": "target_size"
@@ -1668,35 +1645,6 @@
               "min": 1,
               "type": "integer"
             },
-            "keep_metadata": {
-              "availability": "planned",
-              "depends_on": {
-                "metadata": "strip"
-              },
-              "description": "Selectively keep only certain metadata categories and strip the rest \u2014 refines `metadata: strip`. Allowed categories: `copyright`, `gps` (location), `date` (capture time); combinable. `planned` \u2014 selective keep is not yet supported (use `metadata: keep` to preserve everything).",
-              "honored_on": [
-                "same_format"
-              ],
-              "items": {
-                "enum": [
-                  "copyright",
-                  "gps",
-                  "date"
-                ],
-                "type": "string"
-              },
-              "type": "array",
-              "uniqueItems": true
-            },
-            "lossy": {
-              "availability": "planned",
-              "default": false,
-              "description": "Lossy PNG palette quantization \u2014 a large saving for flat-colour PNGs. `planned` \u2014 not yet supported.",
-              "honored_on": [
-                "same_format"
-              ],
-              "type": "boolean"
-            },
             "metadata": {
               "default": "strip",
               "description": "Metadata handling. `strip` = remove all EXIF/IPTC/XMP (default). `keep` = preserve EXIF, colour profile, and XMP. `all` is a DEPRECATED alias of `strip` (kept for older callers; emits Deprecation/Sunset headers \u2014 migrate to `strip`). Any other value is rejected.",
@@ -1746,7 +1694,7 @@
             },
             "quality": {
               "default": 80,
-              "description": "Compression quality (1 = smallest file, 100 = best quality).",
+              "description": "Compression quality (1-100). For PNG this is the SINGLE lossy/lossless control: `quality` < 100 applies lossy palette quantization (imagequant \u2014 licence-cleared for our server-side SaaS backend, `kkajDFXD`; the value is the quantization level), while `quality: 100` keeps the PNG lossless (oxipng optimisation only \u2014 tune the lossless effort via `optimization_level`). 1 = smallest file, 100 = best quality / lossless. There is no separate lossy/lossless toggle for PNG \u2014 it is purely quality-driven.",
               "honored_on": [
                 "same_format"
               ],
@@ -1806,16 +1754,6 @@
                 "auto",
                 "smallest"
               ]
-            },
-            "quality": {
-              "default": 80,
-              "description": "Compression quality (1 = smallest file, 100 = best quality).",
-              "honored_on": [
-                "same_format"
-              ],
-              "max": 100,
-              "min": 1,
-              "type": "integer"
             }
           }
         },
@@ -1836,16 +1774,11 @@
             },
             "color_profile": {
               "default": "keep",
-              "description": "Colour-profile handling \u2014 a dedicated control, separate from `metadata` so that stripping metadata never silently shifts colours. `keep` (default) = preserve your colours: embed the ICC profile where the output format can carry one, otherwise convert to sRGB and bake the colours in so they survive (never a silent drop); `srgb` = convert to sRGB (transform pixels to sRGB, emit untagged \u2014 no embedded ICC, the web default; CMYK/grayscale best-effort); `strip` = drop the profile (smallest \u2014 only when the consumer manages colour itself). On the WebP same-format route `srgb` is `planned` (the byte-level optimiser does not yet run the sRGB transform); `keep` and `strip` are live.",
+              "description": "Colour-profile handling \u2014 a dedicated control, separate from `metadata` so that stripping metadata never silently shifts colours. `keep` (default) = preserve your colours: embed the ICC profile where the output format can carry one, otherwise convert to sRGB and bake the colours in so they survive (never a silent drop); `srgb` = convert to sRGB (transform pixels to sRGB, emit untagged \u2014 no embedded ICC, the web default; CMYK/grayscale best-effort); `strip` = drop the profile (smallest \u2014 only when the consumer manages colour itself). All three values are live on the WebP same-format route \u2014 the sRGB pixel transform is staging-proven (lambdas compression-image git-13b5000: srgb output untagged + a real pixel shift vs strip).",
               "honored_on": [
                 "same_format",
                 "format_change"
               ],
-              "per_value_availability": {
-                "srgb": {
-                  "availability": "planned"
-                }
-              },
               "type": "enum",
               "values": [
                 "keep",
@@ -1855,14 +1788,15 @@
             },
             "encoding_mode": {
               "default": "quality",
-              "description": "Compression mode. `quality` = the `quality` slider drives the encode (default). `target_size` = automatically find the highest quality that fits a byte budget (set via `target_size_bytes`); if the budget can't be met even at the lowest quality, the closest result is returned, and the original is kept if re-encoding wouldn't be smaller.",
+              "description": "Compression mode. `quality` = the `quality` slider drives the encode (default). `target_size` = automatically find the highest quality that fits a byte budget (set via `target_size_bytes`); if the budget can't be met even at the lowest quality, the closest result is returned, and the original is kept if re-encoding wouldn't be smaller. `auto_quality` = hit a named perceptual-quality target (set via `quality_preset`) and let the worker pick the encoder quality that meets it \u2014 the perceptual twin of `target_size` (which targets bytes); the result reports the chosen quality.",
               "honored_on": [
                 "same_format"
               ],
               "type": "enum",
               "values": [
                 "quality",
-                "target_size"
+                "target_size",
+                "auto_quality"
               ]
             },
             "fit": {
@@ -1894,26 +1828,6 @@
               "min": 1,
               "type": "integer"
             },
-            "keep_metadata": {
-              "availability": "planned",
-              "depends_on": {
-                "metadata": "strip"
-              },
-              "description": "Selectively keep only certain metadata categories and strip the rest \u2014 refines `metadata: strip`. Allowed categories: `copyright`, `gps` (location), `date` (capture time); combinable. `planned` \u2014 selective keep is not yet supported (use `metadata: keep` to preserve everything).",
-              "honored_on": [
-                "same_format"
-              ],
-              "items": {
-                "enum": [
-                  "copyright",
-                  "gps",
-                  "date"
-                ],
-                "type": "string"
-              },
-              "type": "array",
-              "uniqueItems": true
-            },
             "lossless": {
               "default": false,
               "depends_on": {
@@ -1975,6 +1889,23 @@
               "min": 1,
               "type": "integer"
             },
+            "quality_preset": {
+              "default": "good",
+              "depends_on": {
+                "encoding_mode": "auto_quality"
+              },
+              "description": "Named perceptual-quality target for `encoding_mode: auto_quality` (best > good > fair > low; `good` is the default). The worker runs a perceptual-target search and picks the encoder quality that meets the named tier \u2014 the wire carries the NAME only, so the tier\u2192target mapping stays worker-internal and calibration-tunable without a contract change. Requires `encoding_mode: auto_quality`. The achieved perceptual score is reported on the result as `metrics.measured_quality` (+ `metrics.quality_metric`).",
+              "honored_on": [
+                "same_format"
+              ],
+              "type": "enum",
+              "values": [
+                "best",
+                "good",
+                "fair",
+                "low"
+              ]
+            },
             "target_size_bytes": {
               "depends_on": {
                 "encoding_mode": "target_size"
@@ -2399,17 +2330,6 @@
               "min": 1,
               "type": "integer"
             }
-          },
-          "per_mime_availability": {
-            "image/avif": {
-              "availability": "beta"
-            },
-            "image/heic": {
-              "availability": "beta"
-            },
-            "image/heif": {
-              "availability": "beta"
-            }
           }
         },
         "image_gif": {
@@ -2507,19 +2427,6 @@
               "min": 1,
               "type": "integer"
             },
-            "metadata": {
-              "availability": "planned",
-              "default": "strip",
-              "description": "Metadata handling for the still-image targets. `planned` \u2014 metadata is not yet preserved 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. `mp4` / `webm` are the GIF\u2192VIDEO transcode targets \u2014 the animated GIF becomes a muted, play-once video (`mp4` = H.264, plays everywhere; `webm` = VP9, smaller), typically far smaller than the original GIF. GIFs are silent (no audio stream); the GIF infinite-loop becomes a playback attribute (`<video loop>`) the player sets, NOT baked into the file.",
               "required": true,
@@ -2634,7 +2541,9 @@
                 "output_format": [
                   "mp4",
                   "webm",
-                  "ogg"
+                  "ogg",
+                  "mov",
+                  "mkv"
                 ]
               },
               "description": "CRF (Constant Rate Factor): 0 = lossless/best, 51 = worst. Lower = higher quality + larger file (the inverse of image `quality`). Video outputs only \u2014 NOT applicable to a `gif` output (frame extraction has no CRF). An explicit `crf` on a `gif` output is rejected as `invalid_options` at workflow-create (the API enforces this `depends_on`); FE/SDK prune it pre-submit.\n",
@@ -2687,14 +2596,16 @@
               "type": "integer"
             },
             "output_format": {
-              "description": "Target format. The video codec is fixed by the container (mp4->H.264, webm->VP9, ogg->Theora, gif->palette) \u2014 not caller-selectable.",
+              "description": "Target format. The video codec is fixed by the container (mp4->H.264, webm->VP9, ogg->Theora, gif->palette, mov->H.264, mkv->H.264) \u2014 not caller-selectable.",
               "required": true,
               "type": "enum",
               "values": [
                 "mp4",
                 "webm",
                 "ogg",
-                "gif"
+                "gif",
+                "mov",
+                "mkv"
               ]
             },
             "trim_end": {
@@ -2703,7 +2614,7 @@
               "type": "float"
             },
             "trim_start": {
-              "description": "Trim from beginning in seconds (absent = from the start). The clip is cut before transcoding \u2014 the user's \"trim a video then make a GIF\" path. The kept clip is [`trim_start`, input_duration \u2212 `trim_end`]. Live for all video outputs (gif/mp4/webm/ogg).\n",
+              "description": "Trim from beginning in seconds (absent = from the start). The clip is cut before transcoding \u2014 the user's \"trim a video then make a GIF\" path. The kept clip is [`trim_start`, input_duration \u2212 `trim_end`]. Live for all video outputs.\n",
               "min": 0,
               "type": "float"
             },
@@ -2844,15 +2755,15 @@
     },
     "image_watermark": {
       "default": false,
-      "description": "Apply an image overlay onto a base media\nasset. Multi-input: exactly one input with role: base (the source\nasset) + exactly one with role: overlay (the watermark). Each input\nis an external_import handle, a vault\nconnection, or an upstream `job_output` (uploads are NOT referenced\ndirectly inside inputs[]). To use an uploaded base or overlay, feed\nit through a `passthrough` source job and reference that job via\n`{ type: job_output, from: <id> }` (per ticket 4som89Uh).\n\nStable today for static-image bases (image/jpeg, image/png,\nimage/webp); animated GIF bases are advertised as `planned` via\nthe parallel `image_gif` mime_group \u2014 schema is contract-defined,\ndispatch returns `feature_not_available` (422) until backend\nsupport ships.\n\nTIFF (image/tiff) and BMP (image/bmp) bases are likewise advertised\nas `planned` via the parallel `image_tiff` / `image_bmp` mime_groups.\nBoth formats are already decodable and the worker's encode arms are a\ncheap add (shared `image`-crate encoders), so each flips to `stable`\nonce its arm ships and is proven. Because watermark output mirrors the\ninput format (`produces: same_as_input`), advertising a base format is\nonly honest when the worker can both decode AND encode it \u2014 which\nholds for TIFF/BMP but not for HEIC/AVIF (no encoder) or SVG (cannot\nre-emit svg from a rasterised composite); those stay out of scope.\n\n**Video bases are NOT supported by `image_watermark`.** Use the\ndedicated `video_watermark` operation\n(`schemas/operations/video_watermark.yaml`), which overlays and\nre-encodes the video.\n\n**Audio is explicitly NOT supported.** For audio overlay (DJ tags,\npodcast intros, jingles), use the `audio_overlay` operation\n(declared in schemas/operations/audio_overlay.yaml at\n`availability: planned`).\n\nSource capped at 100 megapixels for image bases; per-frame caps for\nanimated GIF bases will be defined when the corresponding backend\nsupport ships.\n",
+      "description": "Apply an image overlay onto a base media\nasset. Multi-input: exactly one input with role: base (the source\nasset) + exactly one with role: overlay (the watermark). Each input\nis an external_import handle, a vault\nconnection, or an upstream `job_output` (uploads are NOT referenced\ndirectly inside inputs[]). To use an uploaded base or overlay, feed\nit through a `passthrough` source job and reference that job via\n`{ type: job_output, from: <id> }` (per ticket 4som89Uh).\n\nStable today for static-image bases (image/jpeg, image/png,\nimage/webp); animated GIF bases are advertised as `planned` via\nthe parallel `image_gif` mime_group \u2014 schema is contract-defined,\ndispatch returns `feature_not_available` (422) until backend\nsupport ships.\n\nTIFF (image/tiff) and BMP (image/bmp) bases are now `stable` too\n(flipped planned->stable 2026-06-30 on the lambdas staging proof,\nUANjD38A / #296) via the parallel `image_tiff` / `image_bmp`\nmime_groups. Because watermark output mirrors the input format\n(`produces: same_as_input`), advertising a base format is only honest\nwhen the worker can both decode AND encode it \u2014 which holds for\nTIFF/BMP but not for HEIC/AVIF (no encoder) or SVG (cannot re-emit svg\nfrom a rasterised composite); those stay out of scope.\n\n**Video bases are NOT supported by `image_watermark`.** Use the\ndedicated `video_watermark` operation\n(`schemas/operations/video_watermark.yaml`), which overlays and\nre-encodes the video.\n\n**Audio is explicitly NOT supported.** For audio overlay (DJ tags,\npodcast intros, jingles), use the `audio_overlay` operation\n(declared in schemas/operations/audio_overlay.yaml at\n`availability: planned`).\n\nSource capped at 100 megapixels for image bases; per-frame caps for\nanimated GIF bases will be defined when the corresponding backend\nsupport ships.\n",
       "features": {
         "multi_overlay_stack": {
-          "availability": "planned",
-          "description": "Allow up to 8 overlay inputs per job (currently capped at 1\noverlay). Per-overlay placement via per-input placement options.\nBackend support not yet confirmed; tagged planned. Scope is\nimage-base only at the time this feature was specified; extension\nto GIF / video bases tracks alongside the corresponding mime_group\n`planned` \u2192 `stable` flips.\n"
+          "availability": "stable",
+          "description": "Stack up to 8 overlay inputs on one base image, each with its own\nplacement via the `overlays[]` array option (index-aligned to the\noverlay-role sources; see the `image` group's `overlays` option).\n`overlays[]` is mutually exclusive with the flat single-overlay options,\nwhich remain the 1-overlay back-compat path.\n\n**Base-format scope: multi-overlay (`overlays[]`) is on the `image`\ngroup (jpeg/png/webp) ONLY** \u2014 the format the worker proved. The\nstable `image_tiff` / `image_bmp` bases support the SINGLE-overlay flat\noptions but NOT `overlays[]` yet (multi-overlay on those bases needs its\nown worker proof \u2014 a base-format extension, separate from the group's\nstable single-overlay flip). GIF / video bases remain out of scope.\n\nThe op-level `input` max 9 / `per_role_cardinality` overlay `{1,8}` is\nthe MAXIMUM (the jpeg/png/webp base); input-cardinality has no per-mime-\ngroup primitive, so a `>1`-overlay request on a tiff/bmp base \u2014 which\nhas no `overlays[]` to place the extra overlays \u2014 is rejected as\n`invalid_options` (API + worker). Effective per-base overlay count:\njpeg/png/webp = 1\u20138, tiff/bmp = 1.\n"
         }
       },
       "input_model": "multi",
-      "max_inputs": 2,
+      "max_inputs": 9,
       "mime_groups": {
         "image": {
           "mimes": [
@@ -2900,11 +2811,61 @@
               "description": "Optional overlay width as either pixels (e.g. \"200px\") or\npercentage of base image width (e.g. \"30%\"). Aspect ratio is\npreserved. Omit to use the original overlay size.\n",
               "pattern": "^\\d+(\\.\\d+)?(px|%)$",
               "type": "string"
+            },
+            "overlays": {
+              "description": "Per-overlay placement for the multi-overlay stack \u2014 one entry per\noverlay source, INDEX-ALIGNED: `overlays[i]` applies to overlay\nsource `i`. Stacks up to 8 overlays on one base\n(`features.multi_overlay_stack`). `len(overlays)` MUST equal the\nnumber of overlay-role sources (worker-enforced; `invalid_options`\notherwise).\n\n**Z-order = array index (painter's order, bottom \u2192 top).** Overlays\nare composited in array/source order: `overlays[0]` first (bottom),\nthen `overlays[1]`, \u2026 `overlays[N-1]` LAST (on top). Where two\noverlays overlap, the higher index wins. There is no per-overlay\n`z` field \u2014 the index IS the z-order. (Deterministic in the worker;\nidentical per-frame for animated-WebP bases.)\n\n**Mutually exclusive with the flat single-overlay options**\n(`anchor` / `margin_x` / `margin_y` / `opacity` / `overlay_width`):\na request that sets BOTH `overlays[]` and any flat option is\nrejected as `invalid_options` (API create-validation + worker) \u2014\nthere is no silent precedence. Use the flat options for the\nsingle-overlay path, `overlays[]` for the multi path.\n\nLIVE (flipped `planned` -> stable 2026-07-01 on the lambdas worker\nproof, co-landed with `input` max 2 -> 9 + `per_role_cardinality`\noverlay `{1,8}` + api's overlays[] validation & FNA-gate removal).\nThe single-overlay FLAT options remain the 1-overlay back-compat path.\n",
+              "items": {
+                "properties": {
+                  "anchor": {
+                    "default": "bottom_right",
+                    "description": "9-grid anchor position on the base image (per-overlay; see the flat `anchor`).",
+                    "enum": [
+                      "top_left",
+                      "top_center",
+                      "top_right",
+                      "center_left",
+                      "center",
+                      "center_right",
+                      "bottom_left",
+                      "bottom_center",
+                      "bottom_right"
+                    ],
+                    "type": "string"
+                  },
+                  "margin_x": {
+                    "default": "0px",
+                    "description": "Horizontal offset from the anchor (px or % of base width), anchor-relative (see the flat `margin_x`).",
+                    "pattern": "^\\d+(\\.\\d+)?(px|%)$",
+                    "type": "string"
+                  },
+                  "margin_y": {
+                    "default": "0px",
+                    "description": "Vertical offset from the anchor (px or % of base height), anchor-relative (see the flat `margin_y`).",
+                    "pattern": "^\\d+(\\.\\d+)?(px|%)$",
+                    "type": "string"
+                  },
+                  "opacity": {
+                    "default": 0.5,
+                    "description": "Overlay opacity (0 transparent .. 1 opaque), clamped.",
+                    "maximum": 1,
+                    "minimum": 0,
+                    "type": "number"
+                  },
+                  "overlay_width": {
+                    "description": "Optional overlay width (px or % of base width); aspect preserved. Omit for original size.",
+                    "pattern": "^\\d+(\\.\\d+)?(px|%)$",
+                    "type": "string"
+                  }
+                },
+                "type": "object"
+              },
+              "maxItems": 8,
+              "minItems": 1,
+              "type": "array"
             }
           }
         },
         "image_bmp": {
-          "availability": "planned",
           "mimes": [
             "image/bmp"
           ],
@@ -3000,7 +2961,6 @@
           }
         },
         "image_tiff": {
-          "availability": "planned",
           "mimes": [
             "image/tiff"
           ],
@@ -3055,7 +3015,7 @@
           "min": 1
         },
         "overlay": {
-          "max": 1,
+          "max": 8,
           "min": 1
         }
       },
@@ -4173,7 +4133,7 @@
     },
     "text_watermark": {
       "default": false,
-      "description": "Render a text overlay onto an image using bundled Liberation Sans\n(SIL OFL). Single-input \u2014 text comes from options, not from a file\ninput. Source capped at 100 megapixels in `single` mode. `tiled`\nmode keeps the 25-megapixel canvas bound (see `tile_spacing` /\n`watermark_mode`).\n\nTwo rendering modes:\n- `single`: one label rendered at the anchor + margin position.\n- `tiled`: text tiled across the source image (Cinavia / Adobe Stock\n  pattern); rotation default -45\u00b0 and tile_spacing controls density.\n\nStable today for image/jpeg, image/png, image/webp inputs. TIFF\n(image/tiff) and BMP (image/bmp) inputs are advertised as `planned`\nvia the parallel `image_tiff` / `image_bmp` mime_groups \u2014 both are\nalready decodable and the worker's encode arms are a cheap add\n(shared `image`-crate encoders), so each flips to `stable` once its\narm ships and is proven. Output mirrors the input format\n(`produces: same_as_input`), so a format is only advertised when the\nworker can both decode AND encode it; HEIC/AVIF (no encoder) and SVG\n(cannot re-emit svg from a rasterised composite) stay out of scope.\n",
+      "description": "Render a text overlay onto an image using bundled Liberation Sans\n(SIL OFL). Single-input \u2014 text comes from options, not from a file\ninput. Source capped at 100 megapixels in `single` mode. `tiled`\nmode keeps the 25-megapixel canvas bound (see `tile_spacing` /\n`watermark_mode`).\n\nTwo rendering modes:\n- `single`: one label rendered at the anchor + margin position.\n- `tiled`: text tiled across the source image (Cinavia / Adobe Stock\n  pattern); rotation default -45\u00b0 and tile_spacing controls density.\n\nStable today for image/jpeg, image/png, image/webp inputs. TIFF\n(image/tiff) and BMP (image/bmp) inputs are now `stable` too (flipped\nplanned->stable 2026-06-30 on the lambdas staging proof, UANjD38A /\n#296) via the parallel `image_tiff` / `image_bmp` mime_groups. Output\nmirrors the input format (`produces: same_as_input`), so a format is\nonly advertised when the worker can both decode AND encode it;\nHEIC/AVIF (no encoder) and SVG (cannot re-emit svg from a rasterised\ncomposite) stay out of scope.\n",
       "input_model": "single",
       "mime_groups": {
         "image": {
@@ -4272,7 +4232,6 @@
           }
         },
         "image_bmp": {
-          "availability": "planned",
           "mimes": [
             "image/bmp"
           ],
@@ -4366,7 +4325,6 @@
           }
         },
         "image_tiff": {
-          "availability": "planned",
           "mimes": [
             "image/tiff"
           ],
@@ -4501,10 +4459,9 @@
               ]
             },
             "height": {
-              "description": "Target height in pixels (1-16384; width*height <= 16MP).",
+              "description": "Target height in pixels (1-16384; width*height <= 16MP). Optional \u2014 see `width` for the omitted-default behaviour.",
               "max": 16384,
               "min": 1,
-              "required": true,
               "type": "integer"
             },
             "page": {
@@ -4539,10 +4496,9 @@
               ]
             },
             "width": {
-              "description": "Target width in pixels (1-16384; width*height <= 16MP).",
+              "description": "Target width in pixels (1-16384; width*height <= 16MP). Optional \u2014 when omitted the server applies an aspect-preserving default (both omitted \u2192 longest edge 320px; only one of width/height provided \u2192 the other is derived from the source aspect ratio).",
               "max": 16384,
               "min": 1,
-              "required": true,
               "type": "integer"
             }
           }
@@ -4589,10 +4545,9 @@
               ]
             },
             "height": {
-              "description": "Target height in pixels (1-16384; width*height <= 16MP). For image input this is a full resize, not just a small preview.",
+              "description": "Target height in pixels (1-16384; width*height <= 16MP). For image input this is a full resize. Optional \u2014 see `width` for the omitted-default (aspect-preserving) behaviour.",
               "max": 16384,
               "min": 1,
-              "required": true,
               "type": "integer"
             },
             "quality": {
@@ -4600,91 +4555,19 @@
               "depends_on": {
                 "format": [
                   "jpg",
-                  "webp"
-                ]
-              },
-              "description": "Output quality for lossy thumbnail formats (jpg/webp): higher = better quality, larger file. Ignored for png (lossless).",
-              "max": 100,
-              "min": 1,
-              "type": "integer"
-            },
-            "width": {
-              "description": "Target width in pixels (1-16384; width*height <= 16MP). For image input this is a full resize, not just a small preview.",
-              "max": 16384,
-              "min": 1,
-              "required": true,
-              "type": "integer"
-            }
-          },
-          "per_mime_availability": {
-            "image/avif": {
-              "availability": "beta"
-            },
-            "image/heic": {
-              "availability": "beta"
-            }
-          }
-        },
-        "image_svg": {
-          "availability": "planned",
-          "max_output_pixels": 16000000,
-          "mimes": [
-            "image/svg+xml"
-          ],
-          "options": {
-            "background": {
-              "depends_on": {
-                "format": "jpg"
-              },
-              "description": "Background colour as a 6-digit hex (`#RRGGBB`, e.g. `#ffffff`) for a transparent image (e.g. PNG/WebP with alpha) resized to an opaque JPG thumbnail \u2014 the alpha-flatten fill colour. Mirrors convert.image.background. HEX ONLY: a non-hex value (e.g. a CSS named colour) is rejected rather than advertising an inert free-form string. When omitted, transparency is flattened onto white. JPG output only: PNG/WebP keep alpha, so the flatten (and this option) do not apply.",
-              "pattern": "^#[0-9a-fA-F]{6}$",
-              "type": "string"
-            },
-            "fit": {
-              "default": "crop",
-              "description": "Resize mode",
-              "type": "enum",
-              "values": [
-                "max",
-                "crop",
-                "scale"
-              ]
-            },
-            "format": {
-              "default": "jpg",
-              "description": "Output format for the thumbnail",
-              "type": "enum",
-              "values": [
-                "jpg",
-                "png",
-                "webp"
-              ]
-            },
-            "height": {
-              "description": "Target height in pixels (1-16384; width*height <= 16MP). For image input this is a full resize, not just a small preview.",
-              "max": 16384,
-              "min": 1,
-              "required": true,
-              "type": "integer"
-            },
-            "quality": {
-              "default": 85,
-              "depends_on": {
-                "format": [
-                  "jpg",
-                  "webp"
+                  "webp",
+                  "png"
                 ]
               },
-              "description": "Output quality for lossy thumbnail formats (jpg/webp): higher = better quality, larger file. Ignored for png (lossless).",
+              "description": "Output quality for lossy thumbnail formats (jpg / webp / png): higher = better quality, larger file. For PNG, `quality` < 100 applies lossy palette quantization (imagequant \u2014 transparency preserved); `quality: 100` keeps the PNG lossless. Per-format effective default (server-resolved when `quality` is unset, per ADR-0020 D1): PNG \u2192 70 (more aggressive \u2014 thumbnails target small files), jpg/webp \u2192 85. The schema `default` is the nominal jpg/webp value (85); the FE shows 70 as the initial PNG slider value.",
               "max": 100,
               "min": 1,
               "type": "integer"
             },
             "width": {
-              "description": "Target width in pixels (1-16384; width*height <= 16MP). For image input this is a full resize, not just a small preview.",
+              "description": "Target width in pixels (1-16384; width*height <= 16MP). For image input this is a full resize, not just a small preview. Optional \u2014 when omitted the server applies an aspect-preserving default (both omitted \u2192 longest edge 320px; only one of width/height provided \u2192 the other is derived from the source aspect ratio), so non-square images are never distorted.",
               "max": 16384,
               "min": 1,
-              "required": true,
               "type": "integer"
             }
           }
@@ -4718,10 +4601,9 @@
               ]
             },
             "height": {
-              "description": "Target height in pixels (1-16384; width*height <= 16MP). Rounded down to an even number.",
+              "description": "Target height in pixels (1-16384; width*height <= 16MP). Rounded down to an even number. Optional \u2014 see `width` for the omitted-default behaviour.",
               "max": 16384,
               "min": 1,
-              "required": true,
               "type": "integer"
             },
             "quality": {
@@ -4743,10 +4625,9 @@
               "type": "string"
             },
             "width": {
-              "description": "Target width in pixels (1-16384; width*height <= 16MP). Rounded down to an even number.",
+              "description": "Target width in pixels (1-16384; width*height <= 16MP). Rounded down to an even number. Optional \u2014 when omitted the server applies an aspect-preserving default (both omitted \u2192 longest edge 320px; only one of width/height provided \u2192 the other is derived from the source aspect ratio).",
               "max": 16384,
               "min": 1,
-              "required": true,
               "type": "integer"
             }
           },
@@ -5015,7 +4896,7 @@
       "sole_op": true
     }
   },
-  "schema_version": "2.135.0",
+  "schema_version": "2.152.0",
   "source_commit": null,
   "user_tier": null,
   "workflow_features": {