@giveitsmaller/contracts 0.72.0 → 0.76.0

package/operations/schemas/video_watermark.yaml

@@ -76,8 +76,7 @@ operation:
             max_output_size_bytes: 524288000
         long_form:
           availability: planned
-          required_tier: pro
-          constraints:                            # baseline = Pro
+          constraints:                            # baseline = every tier without a per_tier_constraints override
             max_input_duration: "PT12H"
             max_input_size_bytes: 5000000000       # 5 GB (Pro)
             max_output_size_bytes: 5000000000
@@ -102,38 +101,74 @@ operation:
             - bottom_center
             - bottom_right
           default: bottom_right
-          description: |
-            9-grid anchor position on each video frame. Same vocabulary
-            as `image_watermark.image` and `text_watermark.image`.
+          # AUTHOR NOTES (moved out of the user-facing description, ewOlw35Z,
+          # 2026-09-23 — frontend shows option descriptions to users). Preserved verbatim:
+          #   9-grid anchor position on each video frame. Same vocabulary
+          #   as `image_watermark.image` and `text_watermark.image`.
+          #
+          #   🔴 **`center` IGNORES `margin_x` / `margin_y` rather than
+          #   rejecting them. The rejection as written cannot survive a
+          #   non-zero default; ignoring is the replacement that was CHOSEN.
+          #   The trigger is the DEFAULT, not this operation.** Schema-driven
+          #   clients materialise contract
+          #   defaults BEFORE sending, so with a non-zero default a centred
+          #   request arrives carrying `margin_x: "2%"` whether the caller
+          #   chose it or never mentioned margins. **After materialisation
+          #   an explicit value and a defaulted one are indistinguishable on
+          #   the wire**, so the old `invalid_options` (422) rule would
+          #   refuse nearly every centred watermark.
+          #
+          #   ⚠️ Rejection is not the only alternative — a
+          #   reject-if-it-differs-from-the-default rule would also survive
+          #   materialisation. **Ignoring is the behaviour CHOSEN** under hub
+          #   decision 465, because margins are meaningless when the label is
+          #   centred. The cost is stated: a caller who deliberately passes a
+          #   margin with `anchor: center` gets silence, not a correction.
+          #
+          #   ⚠️ **The trigger is a NON-ZERO DEFAULT, never an operation
+          #   name.** `image_watermark` and `text_watermark` keep their 422
+          #   because their defaults are still `0px`, where a materialised
+          #   default is not non-zero and only a deliberate offset is
+          #   refused.
+          description: >-
+            Where the watermark is placed on each frame, on a 3x3 grid (the same
+            positions as image and text watermarks). With `center`, `margin_x` /
+            `margin_y` are ignored.
 
         margin_x:
           type: string
           pattern: '^\d+(\.\d+)?(px|%)$'
-          default: "0px"
+          default: "2%"
           description: |
             Horizontal offset from the anchor as pixels (e.g. "40px")
             or percentage of video frame width (e.g. "5%"). Direction
             is anchor-relative — positive moves toward the frame
             centre.
 
-            **`anchor: center` exception.** When the anchor is `center`
-            the centre is the centre — there is no anchor-relative
-            direction. Non-zero `margin_x` combined with
-            `anchor: center` is rejected by the API at workflow-create
-            time as `invalid_options` (HTTP 422). Same rule as the
-            other watermark operations.
+            **Defaults to `2%`, i.e. INSET from the frame edge**, because
+            a watermark flush against the edge is the wrong default for
+            video: player chrome, safe-area cropping and letterboxing all
+            eat the outermost pixels. **A true flush remains available by
+            passing `"0px"` explicitly.**
+
+            **`anchor: center`: margins are IGNORED.** The centre is the
+            centre — there is no anchor-relative direction — so this is a
+            silent no-op rather than a rejection. See the `anchor`
+            description for why a rejection is not usable with a non-zero
+            default.
 
         margin_y:
           type: string
           pattern: '^\d+(\.\d+)?(px|%)$'
-          default: "0px"
+          default: "2%"
           description: |
             Vertical offset from the anchor as pixels or percentage of
             video frame height. Anchor-relative; positive moves toward
             the frame centre.
 
-            **`anchor: center` exception.** Same rejection rule as
-            `margin_x`.
+            **Defaults to `2%` (inset), for the reasons on `margin_x`**;
+            `"0px"` still gives a true flush. **`anchor: center`: margins
+            are IGNORED**, same as `margin_x`.
 
         opacity:
           type: float

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@giveitsmaller/contracts",
-  "version": "0.72.0",
-  "description": "Generated contract types for GISL (Give It Smaller). Generated from compression_contracts spec v2.203.0.",
-  "gislContractsSpec": "v2.203.0",
+  "version": "0.76.0",
+  "description": "Generated contract types for GISL (Give It Smaller). Generated from compression_contracts spec v2.211.0.",
+  "gislContractsSpec": "v2.211.0",
   "license": "Apache-2.0",
   "homepage": "https://docs.giveitsmaller.com",
   "bugs": {