@giveitsmaller/contracts 0.48.0 → 0.51.0

package/operations/schemas/image_watermark.yaml

@@ -18,15 +18,14 @@ operation:
     dispatch returns `feature_not_available` (422) until backend
     support ships.
 
-    TIFF (image/tiff) and BMP (image/bmp) bases are likewise advertised
-    as `planned` via the parallel `image_tiff` / `image_bmp` mime_groups.
-    Both formats are already decodable and the worker's encode arms are a
-    cheap add (shared `image`-crate encoders), so each flips to `stable`
-    once its arm ships and is proven. Because watermark output mirrors the
-    input format (`produces: same_as_input`), advertising a base format is
-    only honest when the worker can both decode AND encode it — which
-    holds for TIFF/BMP but not for HEIC/AVIF (no encoder) or SVG (cannot
-    re-emit svg from a rasterised composite); those stay out of scope.
+    TIFF (image/tiff) and BMP (image/bmp) bases are now `stable` too
+    (flipped planned->stable 2026-06-30 on the lambdas staging proof,
+    UANjD38A / #296) via the parallel `image_tiff` / `image_bmp`
+    mime_groups. Because watermark output mirrors the input format
+    (`produces: same_as_input`), advertising a base format is only honest
+    when the worker can both decode AND encode it — which holds for
+    TIFF/BMP but not for HEIC/AVIF (no encoder) or SVG (cannot re-emit svg
+    from a rasterised composite); those stay out of scope.
 
     **Video bases are NOT supported by `image_watermark`.** Use the
     dedicated `video_watermark` operation
@@ -45,30 +44,53 @@ operation:
   input_model: multi
   sole_op: true   # bypasses V1 chain validation — must be the only operation in its job (ADR-0025)
   min_inputs: 2
-  max_inputs: 2
+  max_inputs: 9
 
-  # Per-role input-count constraints (ADR-0015). Both roles REQUIRED,
-  # exactly one each. Arithmetic-consistency rule (CI-checked):
-  # - sum(role.min) == min_inputs  (1 + 1 = 2)
-  # - sum(role.max) == max_inputs  (1 + 1 = 2)
+  # Per-role input-count constraints (ADR-0015). base REQUIRED exactly one;
+  # overlay 1-8 (multi-overlay stack LIVE 2026-07-01). Arithmetic-consistency
+  # rule (CI-checked): sum(role.min) == min_inputs (1 + 1 = 2); sum(role.max) ==
+  # max_inputs (1 + 8 = 9). Per-role counts are WORKER-enforced (the API validates
+  # only the coarse TOTAL via input min/max); per_role_cardinality is advisory.
   per_role_cardinality:
     base:
       min: 1
       max: 1
     overlay:
       min: 1
-      max: 1
+      max: 8
 
   features:
     multi_overlay_stack:
-      availability: planned
+      # LIVE 2026-07-01: flipped planned->stable on the lambdas worker proof
+      # (operation-image-watermark git-2999507, digest-verified;
+      # prove-multi-overlay-staging.sh — 3 index-aligned overlays each rendering
+      # their own colour at their anchor; mutex + cardinality worker-enforced).
+      # Co-landed with `input` max 2->9 + per_role overlay{1,8} + overlays[]
+      # executable + api's overlays[] validation & FNA-gate removal (uUdre4jg).
+      # availability set EXPLICITLY (matches the audio_overlay / video_watermark
+      # multi_overlay_stack features, which stay `planned` — their workers are
+      # unproven for multi-overlay).
+      availability: stable
       description: |
-        Allow up to 8 overlay inputs per job (currently capped at 1
-        overlay). Per-overlay placement via per-input placement options.
-        Backend support not yet confirmed; tagged planned. Scope is
-        image-base only at the time this feature was specified; extension
-        to GIF / video bases tracks alongside the corresponding mime_group
-        `planned` → `stable` flips.
+        Stack up to 8 overlay inputs on one base image, each with its own
+        placement via the `overlays[]` array option (index-aligned to the
+        overlay-role sources; see the `image` group's `overlays` option).
+        `overlays[]` is mutually exclusive with the flat single-overlay options,
+        which remain the 1-overlay back-compat path.
+
+        **Base-format scope: multi-overlay (`overlays[]`) is on the `image`
+        group (jpeg/png/webp) ONLY** — the format the worker proved. The
+        stable `image_tiff` / `image_bmp` bases support the SINGLE-overlay flat
+        options but NOT `overlays[]` yet (multi-overlay on those bases needs its
+        own worker proof — a base-format extension, separate from the group's
+        stable single-overlay flip). GIF / video bases remain out of scope.
+
+        The op-level `input` max 9 / `per_role_cardinality` overlay `{1,8}` is
+        the MAXIMUM (the jpeg/png/webp base); input-cardinality has no per-mime-
+        group primitive, so a `>1`-overlay request on a tiff/bmp base — which
+        has no `overlays[]` to place the extra overlays — is rejected as
+        `invalid_options` (API + worker). Effective per-base overlay count:
+        jpeg/png/webp = 1–8, tiff/bmp = 1.
 
   mime_groups:
     image:
@@ -145,6 +167,91 @@ operation:
             Optional overlay width as either pixels (e.g. "200px") or
             percentage of base image width (e.g. "30%"). Aspect ratio is
             preserved. Omit to use the original overlay size.
+        overlays:
+          type: array
+          minItems: 1
+          maxItems: 8
+          # LIVE 2026-07-01 (no availability tag = stable): the multi-overlay-stack
+          # surface (features.multi_overlay_stack), flipped planned->stable on the
+          # lambdas worker proof (git-2999507). INDEX-ALIGNED to the overlay-role
+          # sources: overlays[i] applies to overlay source i. The option DSL has no
+          # source-array-length-match primitive, so `len(overlays) == overlay-source
+          # count` is WORKER-enforced (invalid_options otherwise) — prose below.
+          # Cardinality (co-design with lambdas + api): per-role counts are
+          # WORKER-enforced (base{1,1} + overlay{1,8}); the API validates only the
+          # coarse TOTAL input count via `input` min/max (2..9), so
+          # per_role_cardinality stays ADVISORY. The item sub-schema mirrors the flat
+          # single-overlay options (JSON-Schema forms per the render_variants.targets
+          # array-of-objects precedent).
+          # COEXISTENCE: `overlays[]` is MUTUALLY EXCLUSIVE with the flat
+          # single-overlay options (anchor/margin_x/margin_y/opacity/
+          # overlay_width) — setting both in one request is `invalid_options`
+          # (api create-validation + worker). No silent precedence; the caller
+          # picks ONE mode. (The option DSL has no cross-option-group mutex
+          # primitive, so this is validator-enforced, documented here + in prose.)
+          description: |
+            Per-overlay placement for the multi-overlay stack — one entry per
+            overlay source, INDEX-ALIGNED: `overlays[i]` applies to overlay
+            source `i`. Stacks up to 8 overlays on one base
+            (`features.multi_overlay_stack`). `len(overlays)` MUST equal the
+            number of overlay-role sources (worker-enforced; `invalid_options`
+            otherwise).
+
+            **Z-order = array index (painter's order, bottom → top).** Overlays
+            are composited in array/source order: `overlays[0]` first (bottom),
+            then `overlays[1]`, … `overlays[N-1]` LAST (on top). Where two
+            overlays overlap, the higher index wins. There is no per-overlay
+            `z` field — the index IS the z-order. (Deterministic in the worker;
+            identical per-frame for animated-WebP bases.)
+
+            **Mutually exclusive with the flat single-overlay options**
+            (`anchor` / `margin_x` / `margin_y` / `opacity` / `overlay_width`):
+            a request that sets BOTH `overlays[]` and any flat option is
+            rejected as `invalid_options` (API create-validation + worker) —
+            there is no silent precedence. Use the flat options for the
+            single-overlay path, `overlays[]` for the multi path.
+
+            LIVE (flipped `planned` -> stable 2026-07-01 on the lambdas worker
+            proof, co-landed with `input` max 2 -> 9 + `per_role_cardinality`
+            overlay `{1,8}` + api's overlays[] validation & FNA-gate removal).
+            The single-overlay FLAT options remain the 1-overlay back-compat path.
+          items:
+            type: object
+            properties:
+              anchor:
+                type: string
+                enum:
+                  - top_left
+                  - top_center
+                  - top_right
+                  - center_left
+                  - center
+                  - center_right
+                  - bottom_left
+                  - bottom_center
+                  - bottom_right
+                default: bottom_right
+                description: 9-grid anchor position on the base image (per-overlay; see the flat `anchor`).
+              margin_x:
+                type: string
+                pattern: '^\d+(\.\d+)?(px|%)$'
+                default: "0px"
+                description: Horizontal offset from the anchor (px or % of base width), anchor-relative (see the flat `margin_x`).
+              margin_y:
+                type: string
+                pattern: '^\d+(\.\d+)?(px|%)$'
+                default: "0px"
+                description: Vertical offset from the anchor (px or % of base height), anchor-relative (see the flat `margin_y`).
+              opacity:
+                type: number
+                minimum: 0
+                maximum: 1
+                default: 0.5
+                description: Overlay opacity (0 transparent .. 1 opaque), clamped.
+              overlay_width:
+                type: string
+                pattern: '^\d+(\.\d+)?(px|%)$'
+                description: Optional overlay width (px or % of base width); aspect preserved. Omit for original size.
 
     # Animated GIF base — separate group because the rendering path is
     # frame-preserving (each frame composited with the overlay), distinct
@@ -217,12 +324,13 @@ operation:
             width. Aspect ratio preserved. Omit to use the original
             overlay size.
 
-    # TIFF base — separate group because backend support ships in its own
-    # wave: the format is already decodable, but the encode arm (shared
-    # `image`-crate TiffEncoder) is pending. Tagged `planned` until the arm
-    # ships and is proven, then flips to `stable` (cross-repo UANjD38A).
+    # TIFF base — separate group (its backend arm shipped in its own wave).
+    # Now STABLE (flipped 2026-06-30 — see the group comment below).
     image_tiff:
-      availability: planned
+      # planned->stable 2026-06-30 (UANjD38A): lambdas staging-proved the TIFF
+      # image-watermark encode (composited output md5 != base, decodable as TIFF,
+      # PR #296 c664d80; encoder shipped dark in #274). Manifest lists image/tiff in
+      # accepts + outputs.
       mimes:
         - image/tiff
       options:
@@ -289,11 +397,12 @@ operation:
             width. Aspect ratio preserved. Omit to use the original
             overlay size.
 
-    # BMP base — separate group for the same reason as image_tiff: decode
-    # is ready, the encode arm (shared `image`-crate BmpEncoder) is pending.
-    # Tagged `planned` until the arm ships and is proven (cross-repo UANjD38A).
+    # BMP base — separate group for the same reason as image_tiff. Now
+    # STABLE (flipped 2026-06-30 — see the group comment below).
     image_bmp:
-      availability: planned
+      # planned->stable 2026-06-30 (UANjD38A): lambdas staging-proved the BMP
+      # image-watermark encode (composited + decodable as BMP, PR #296 c664d80;
+      # encoder shipped dark in #274). Manifest lists image/bmp in accepts + outputs.
       mimes:
         - image/bmp
       options:

package/operations/schemas/text_watermark.yaml

@@ -15,14 +15,13 @@ operation:
       pattern); rotation default -45° and tile_spacing controls density.
 
     Stable today for image/jpeg, image/png, image/webp inputs. TIFF
-    (image/tiff) and BMP (image/bmp) inputs are advertised as `planned`
-    via the parallel `image_tiff` / `image_bmp` mime_groups — both are
-    already decodable and the worker's encode arms are a cheap add
-    (shared `image`-crate encoders), so each flips to `stable` once its
-    arm ships and is proven. Output mirrors the input format
-    (`produces: same_as_input`), so a format is only advertised when the
-    worker can both decode AND encode it; HEIC/AVIF (no encoder) and SVG
-    (cannot re-emit svg from a rasterised composite) stay out of scope.
+    (image/tiff) and BMP (image/bmp) inputs are now `stable` too (flipped
+    planned->stable 2026-06-30 on the lambdas staging proof, UANjD38A /
+    #296) via the parallel `image_tiff` / `image_bmp` mime_groups. Output
+    mirrors the input format (`produces: same_as_input`), so a format is
+    only advertised when the worker can both decode AND encode it;
+    HEIC/AVIF (no encoder) and SVG (cannot re-emit svg from a rasterised
+    composite) stay out of scope.
   default: false
   input_model: single
   sole_op: true   # bypasses V1 chain validation — must be the only operation in its job (ADR-0025)
@@ -158,14 +157,14 @@ operation:
             `color` already encodes transparency, so opacity is usually
             left at 1.0 and transparency is set via the color hex.
 
-    # TIFF input — separate group because backend support ships in its own
-    # wave: the format is already decodable, but the encode arm (shared
-    # `image`-crate TiffEncoder) is pending. Tagged `planned` until the arm
-    # ships and is proven, then flips to `stable` (cross-repo UANjD38A).
+    # TIFF input — separate group (its backend arm shipped in its own wave).
+    # Now STABLE (flipped 2026-06-30 — see the group comment below).
     # Text-rendering options are format-independent, so the shape mirrors
     # the canonical `image` group exactly.
     image_tiff:
-      availability: planned
+      # planned->stable 2026-06-30 (UANjD38A): lambdas staging-proved the TIFF
+      # text-watermark encode (composited + decodable as TIFF, PR #296 c664d80;
+      # encoder shipped dark in #274). Manifest lists image/tiff in accepts + outputs.
       mimes:
         - image/tiff
       options:
@@ -284,11 +283,12 @@ operation:
             `color` already encodes transparency, so opacity is usually
             left at 1.0 and transparency is set via the color hex.
 
-    # BMP input — separate group for the same reason as image_tiff: decode
-    # is ready, the encode arm (shared `image`-crate BmpEncoder) is pending.
-    # Tagged `planned` until the arm ships and is proven (cross-repo UANjD38A).
+    # BMP input — separate group for the same reason as image_tiff. Now
+    # STABLE (flipped 2026-06-30 — see the group comment below).
     image_bmp:
-      availability: planned
+      # planned->stable 2026-06-30 (UANjD38A): lambdas staging-proved the BMP
+      # text-watermark encode (composited + decodable as BMP, PR #296 c664d80;
+      # encoder shipped dark in #274). Manifest lists image/bmp in accepts + outputs.
       mimes:
         - image/bmp
       options:

package/operations/schemas/thumbnail.yaml

@@ -17,12 +17,12 @@ operation:
         - image/bmp
         - image/avif
         - image/heic
-      per_mime_availability:
-        # avif/heic decode shipped in the thumbnail-image worker via libheif
-        # (lambdas w34Taquf, #210). beta: live + opt-in, shape-stable.
-        # Re-add after the v2.67.0 interim crash-window drop (aYPbNVKD Phase 2).
-        image/avif: { availability: beta }
-        image/heic: { availability: beta }
+      # avif/heic decode in the thumbnail-image worker via libheif (lambdas
+      # w34Taquf, #210) is now GA-STABLE — no per_mime_availability tag = stable
+      # (the group default), promoted beta→stable 2026-06-30 on the lambdas GA
+      # attestation: libheif decode LIVE on staging since 2026-06-14, e2e
+      # decode-smoke green, zero decode failures since. Standard files are GA;
+      # exotic variants (10-bit / HDR / multi-image HEIC) decode best-effort.
       # Output-area wall (lambdas thumbnail-image MAX_OUTPUT_PIXELS): the FE
       # pre-validates width*height <= max_output_pixels. The per-axis max (16384)
       # is NOT the real limit — e.g. 6000x6000 (36MP) is rejected though each axis
@@ -36,72 +36,20 @@ operation:
           type: integer
           min: 1
           max: 16384
-          required: true
-          description: "Target width in pixels (1-16384; width*height <= 16MP). For image input this is a full resize, not just a small preview."
-        height:
-          type: integer
-          min: 1
-          max: 16384
-          required: true
-          description: "Target height in pixels (1-16384; width*height <= 16MP). For image input this is a full resize, not just a small preview."
-        fit:
-          type: enum
-          values: [max, crop, scale]
-          default: crop
-          description: "Resize mode"
-        format:
-          type: enum
-          values: [jpg, png, webp]
-          default: jpg
-          description: "Output format for the thumbnail"
-        quality:
-          type: integer
-          min: 1
-          max: 100
-          default: 85
-          depends_on: { format: [jpg, webp] }
-          description: "Output quality for lossy thumbnail formats (jpg/webp): higher = better quality, larger file. Ignored for png (lossless)."
-        background:
-          type: string
-          pattern: "^#[0-9a-fA-F]{6}$"
-          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 — 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.
-
-    # SVG input (planned, UANjD38A). SVG is split into its own parallel mime_group
-    # (group-level `availability: planned`, which the API gates -> feature_not_available)
-    # rather than tagged inside the stable `image` group, because per-MIME planned is
-    # advisory/not enforced. SVG rasterises to a bitmap cleanly, so render->resize for
-    # thumbnail is feasible. Flip planned -> stable
-    # (or beta) once the worker proves svg-rasterise input. Shares the `image` group's
-    # option shape (FORMAT.md "Parallel groups").
-    image_svg:
-      availability: planned
-      mimes:
-        - image/svg+xml
-      max_output_pixels: 16000000
-      options:
-        # IMAGE input is a full resizer (Lanczos): width/height accept the
-        # worker's real 1-16384px range (area-capped above) — this op is the
-        # image-resize path, surfaced in the UI as "Resize", not only thumbnails.
-        width:
-          type: integer
-          min: 1
-          max: 16384
-          required: true
-          description: "Target width in pixels (1-16384; width*height <= 16MP). For image input this is a full resize, not just a small preview."
+            Target width in pixels (1-16384; width*height <= 16MP). For image input
+            this is a full resize, not just a small preview. Optional — when omitted
+            the server applies an aspect-preserving default (both omitted → longest
+            edge 320px; only one of width/height provided → the other is derived from
+            the source aspect ratio), so non-square images are never distorted.
         height:
           type: integer
           min: 1
           max: 16384
-          required: true
-          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 — see `width` for the omitted-default
+            (aspect-preserving) behaviour.
         fit:
           type: enum
           values: [max, crop, scale]
@@ -117,8 +65,15 @@ operation:
           min: 1
           max: 100
           default: 85
-          depends_on: { format: [jpg, webp] }
-          description: "Output quality for lossy thumbnail formats (jpg/webp): higher = better quality, larger file. Ignored for png (lossless)."
+          depends_on: { format: [jpg, webp, png] }
+          description: >-
+            Output quality for lossy thumbnail formats (jpg / webp / png): higher =
+            better quality, larger file. For PNG, `quality` < 100 applies lossy palette
+            quantization (imagequant — transparency preserved); `quality: 100` keeps the
+            PNG lossless. Per-format effective default (server-resolved when `quality`
+            is unset, per ADR-0020 D1): PNG → 70 (more aggressive — thumbnails target
+            small files), jpg/webp → 85. The schema `default` is the nominal jpg/webp
+            value (85); the FE shows 70 as the initial PNG slider value.
         background:
           type: string
           pattern: "^#[0-9a-fA-F]{6}$"
@@ -175,14 +130,18 @@ operation:
           type: integer
           min: 1
           max: 16384
-          required: true
-          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 — when omitted the server applies an aspect-preserving
+            default (both omitted → longest edge 320px; only one of width/height
+            provided → the other is derived from the source aspect ratio).
         height:
           type: integer
           min: 1
           max: 16384
-          required: true
-          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 — see `width` for the omitted-default behaviour.
         fit:
           type: enum
           values: [max, crop, scale]
@@ -237,14 +196,18 @@ operation:
           type: integer
           min: 1
           max: 16384
-          required: true
-          description: "Target width in pixels (1-16384; width*height <= 16MP)."
+          description: >-
+            Target width in pixels (1-16384; width*height <= 16MP). Optional — when
+            omitted the server applies an aspect-preserving default (both omitted →
+            longest edge 320px; only one of width/height provided → the other is
+            derived from the source aspect ratio).
         height:
           type: integer
           min: 1
           max: 16384
-          required: true
-          description: "Target height in pixels (1-16384; width*height <= 16MP)."
+          description: >-
+            Target height in pixels (1-16384; width*height <= 16MP). Optional — see
+            `width` for the omitted-default behaviour.
         fit:
           type: enum
           values: [max, crop, scale]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@giveitsmaller/contracts",
-  "version": "0.48.0",
+  "version": "0.51.0",
   "description": "Generated contract types for GISL (Give It Smaller)",
   "license": "MIT",
   "type": "module",