@giveitsmaller/contracts 0.35.0 → 0.36.0

package/operations/schemas/compress.yaml

@@ -44,13 +44,16 @@ operation:
     # see FORMAT.md §"Route-aware Output model"). The derived per-(media, route,
     # output_format) projection is accepted-options/image-output-routes.json.
     #
-    # RESIZE-INSIDE-OUTPUT ships STABLE (hub-directed fast-path, 2026-06-22):
-    #   width / height / fit + max_output_pixels — backed by the PROVEN image
-    #   resize engine (thumbnail-images Lanczos, 1-16384, 16MP cap; live), routed
-    #   onto the Output path. Resize is a REPLACE transform inside Output (ONE
-    #   transformed output) — NOT thumbnail's derivative/preview semantics;
-    #   thumbnail.yaml stays the preview op untouched. Flat keys keyed to the
-    #   Output (compress) op, matching thumbnail.yaml's resize shape.
+    # RESIZE-INSIDE-OUTPUT ships STABLE (hub-directed fast-path, 2026-06-22;
+    # engine corrected per API worker-verification n4CmaDE8, 2026-06-23):
+    #   width / height / fit + max_output_pixels. The CONVERT worker is the image
+    #   resize engine for the WHOLE Output op (image_convert.rs, Lanczos, 1-16384,
+    #   16MP cap, svg-reject; live #257) — the compress optimiser has NO resize.
+    #   The API routes BOTH arms through convert (same_format = convert to the same
+    #   token; format_change = convert to the target), so these keys are declared
+    #   HERE (the facade entry) AND on convert.image (where the worker reads them +
+    #   the API re-validates the rewritten op). REPLACE transform, ONE output —
+    #   NOT thumbnail's derivative/preview semantics; thumbnail.yaml untouched.
     #
     # STABLE on the optimiser (same_format) route (all worker-proven 2026-06-23):
     #   lossless (jpeg/webp) — worker honours the `lossless` bool, API emits it.
@@ -67,7 +70,7 @@ operation:
     image_jpeg:
       mimes:
         - image/jpeg
-      # Resize-inside-Output (planned) shares thumbnail-image's 16MP output-area
+      # Resize-inside-Output shares the convert resize engine's 16MP output-area
       # wall — the per-axis 16384 cap can't express it (FORMAT.md §max_output_pixels).
       max_output_pixels: 16000000
       options:
@@ -76,8 +79,36 @@ operation:
           min: 1
           max: 100
           default: 80
+          depends_on: { encoding_mode: quality }
           honored_on: [same_format]
-          description: "Compression quality (1 = smallest file, 100 = best 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.
+        encoding_mode:
+          type: enum
+          values: [quality, target_size]
+          default: quality
+          per_value_availability:
+            target_size: { availability: planned }
+          honored_on: [same_format]
+          description: >-
+            Compression mode (mirrors compress.video). `quality` = the `quality`
+            slider drives the encode (default, live). `target_size` = `planned` —
+            hit a byte budget via the worker's encode-measure-binary-search loop
+            (lambdas building; jpeg/webp/avif only). Optimiser (same_format) route.
+        target_size_bytes:
+          type: integer
+          min: 1024
+          availability: planned
+          depends_on: { encoding_mode: target_size }
+          honored_on: [same_format]
+          description: >-
+            Target output size in bytes (min 1024 = 1 KiB). `planned` — 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).
+            Optimiser (same_format) route.
         metadata:
           type: enum
           values: [all, keep]
@@ -105,13 +136,16 @@ operation:
         lossless:
           type: boolean
           default: false
+          depends_on: { encoding_mode: quality }
           honored_on: [same_format]
           description: >-
             Lossless JPEG re-optimisation (optimiser path): optimises the Huffman
             tables WITHOUT re-encoding pixels — bit-preserving on the pixel data,
             no quality loss (it cannot recover detail a lossy JPEG already lost).
             STABLE — the compress-image worker honours the `lossless` bool
-            (un-parked 2026-06-23). Optimiser (same_format) route only.
+            (un-parked 2026-06-23). Only in `quality` mode — incompatible with
+            `target_size` (the byte-budget loop is inherently lossy). Optimiser
+            (same_format) route only.
         width:
           type: integer
           min: 1
@@ -120,8 +154,9 @@ operation:
           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) — it is NOT the derivative `thumbnail` op.
+            ONE transformed output) using the proven convert resize engine (Lanczos;
+            the API routes Output resize through the convert worker, BOTH routes —
+            the compress optimiser has no resize) — it is NOT the derivative `thumbnail` op.
             Optional; omit to keep the source dimensions.
         height:
           type: integer
@@ -136,9 +171,12 @@ operation:
           depends_on: { width: set, height: set, logic: or }
           honored_on: [same_format, format_change]
           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.
+            Resize mode. `max` (default) = fit within bounds, preserving aspect ratio
+            and NEVER upscaling — it caps at the source dimensions. This IS the
+            "no-enlarge" behaviour (there is no separate `no_enlarge` flag — 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.
 
     image_png:
       mimes:
@@ -197,8 +235,9 @@ operation:
           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) — it is NOT the derivative `thumbnail` op.
+            ONE transformed output) using the proven convert resize engine (Lanczos;
+            the API routes Output resize through the convert worker, BOTH routes —
+            the compress optimiser has no resize) — it is NOT the derivative `thumbnail` op.
             Optional; omit to keep the source dimensions.
         height:
           type: integer
@@ -213,9 +252,12 @@ operation:
           depends_on: { width: set, height: set, logic: or }
           honored_on: [same_format, format_change]
           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.
+            Resize mode. `max` (default) = fit within bounds, preserving aspect ratio
+            and NEVER upscaling — it caps at the source dimensions. This IS the
+            "no-enlarge" behaviour (there is no separate `no_enlarge` flag — 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.
 
     image_avif:
       availability: beta
@@ -237,8 +279,37 @@ operation:
           min: 1
           max: 100
           default: 80
+          depends_on: { encoding_mode: quality }
           honored_on: [same_format]
-          description: "Compression quality (1 = smallest file, 100 = best 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.
+        encoding_mode:
+          type: enum
+          values: [quality, target_size]
+          default: quality
+          per_value_availability:
+            target_size: { availability: planned }
+          honored_on: [same_format]
+          description: >-
+            Compression mode (mirrors compress.video). `quality` = the `quality`
+            slider drives the encode (default, live). `target_size` = `planned` —
+            hit a byte budget via the worker's encode-measure-binary-search loop
+            (lambdas building; jpeg/webp/avif only). AVIF encodes are slow, so the
+            loop caps iterations. Optimiser (same_format) route.
+        target_size_bytes:
+          type: integer
+          min: 1024
+          availability: planned
+          depends_on: { encoding_mode: target_size }
+          honored_on: [same_format]
+          description: >-
+            Target output size in bytes (min 1024 = 1 KiB). `planned` — 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).
+            Optimiser (same_format) route.
         metadata:
           type: enum
           values: [all]
@@ -273,8 +344,9 @@ operation:
           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) — it is NOT the derivative `thumbnail` op.
+            ONE transformed output) using the proven convert resize engine (Lanczos;
+            the API routes Output resize through the convert worker, BOTH routes —
+            the compress optimiser has no resize) — it is NOT the derivative `thumbnail` op.
             Optional; omit to keep the source dimensions.
         height:
           type: integer
@@ -289,9 +361,12 @@ operation:
           depends_on: { width: set, height: set, logic: or }
           honored_on: [same_format, format_change]
           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.
+            Resize mode. `max` (default) = fit within bounds, preserving aspect ratio
+            and NEVER upscaling — it caps at the source dimensions. This IS the
+            "no-enlarge" behaviour (there is no separate `no_enlarge` flag — 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.
 
     # webp split out of the former bundled image group: it is the one input that
     # carries BOTH Resize (raster, proven in thumbnail-images) AND the optimiser
@@ -307,8 +382,36 @@ operation:
           min: 1
           max: 100
           default: 80
+          depends_on: { encoding_mode: quality }
           honored_on: [same_format]
-          description: "Compression quality (1 = smallest file, 100 = best 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.
+        encoding_mode:
+          type: enum
+          values: [quality, target_size]
+          default: quality
+          per_value_availability:
+            target_size: { availability: planned }
+          honored_on: [same_format]
+          description: >-
+            Compression mode (mirrors compress.video). `quality` = the `quality`
+            slider drives the encode (default, live). `target_size` = `planned` —
+            hit a byte budget via the worker's encode-measure-binary-search loop
+            (lambdas building; jpeg/webp/avif only). Optimiser (same_format) route.
+        target_size_bytes:
+          type: integer
+          min: 1024
+          availability: planned
+          depends_on: { encoding_mode: target_size }
+          honored_on: [same_format]
+          description: >-
+            Target output size in bytes (min 1024 = 1 KiB). `planned` — 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).
+            Optimiser (same_format) route.
         metadata:
           type: enum
           values: [all, keep]
@@ -331,12 +434,15 @@ operation:
         lossless:
           type: boolean
           default: false
+          depends_on: { encoding_mode: quality }
           honored_on: [same_format]
           description: >-
             Encode WebP losslessly (optimiser path): a genuine lossless WebP encode.
             STABLE — 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.
+            same visual quality. Only in `quality` mode — incompatible with
+            `target_size` (the byte-budget loop is inherently lossy). Optimiser
+            (same_format) route only.
         width:
           type: integer
           min: 1
@@ -345,8 +451,9 @@ operation:
           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) — it is NOT the derivative `thumbnail` op.
+            ONE transformed output) using the proven convert resize engine (Lanczos;
+            the API routes Output resize through the convert worker, BOTH routes —
+            the compress optimiser has no resize) — it is NOT the derivative `thumbnail` op.
             Optional; omit to keep the source dimensions.
         height:
           type: integer
@@ -361,9 +468,12 @@ operation:
           depends_on: { width: set, height: set, logic: or }
           honored_on: [same_format, format_change]
           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.
+            Resize mode. `max` (default) = fit within bounds, preserving aspect ratio
+            and NEVER upscaling — it caps at the source dimensions. This IS the
+            "no-enlarge" behaviour (there is no separate `no_enlarge` flag — 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.
 
     # svg is VECTOR: no raster resize (thumbnail-images does not list svg), and the
     # optimiser `lossless` knob does not apply. SVG compression is SVGO; only
@@ -440,8 +550,9 @@ operation:
           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) — it is NOT the derivative `thumbnail` op.
+            ONE transformed output) using the proven convert resize engine (Lanczos;
+            the API routes Output resize through the convert worker, BOTH routes —
+            the compress optimiser has no resize) — it is NOT the derivative `thumbnail` op.
             Optional; omit to keep the source dimensions.
         height:
           type: integer
@@ -456,9 +567,12 @@ operation:
           depends_on: { width: set, height: set, logic: or }
           honored_on: [same_format, format_change]
           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.
+            Resize mode. `max` (default) = fit within bounds, preserving aspect ratio
+            and NEVER upscaling — it caps at the source dimensions. This IS the
+            "no-enlarge" behaviour (there is no separate `no_enlarge` flag — 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.
 
     audio:
       mimes:

package/operations/schemas/convert.yaml

@@ -8,12 +8,16 @@ operation:
 
   mime_groups:
     image:
+      # svg is split into convert.image_svg (below): it rasterises to raster
+      # formats but CANNOT be raster-resized (worker rejects svg resize), so it
+      # must NOT sit in a group that declares width/height/fit — else the raw
+      # schema / availability / accepted-options advertise svg resize. Mirrors
+      # compress.image_svg.
       mimes:
         - image/jpeg
         - image/png
         - image/gif
         - image/webp
-        - image/svg+xml
         - image/tiff
         - image/bmp
         - image/vnd.microsoft.icon
@@ -33,6 +37,20 @@ operation:
       # output_format) projection (accepted-options/image-output-routes.json)
       # attributes them to the transcoder path — `background` is the canonical
       # transparency→JPEG fill on format-change-to-jpeg, already live + stable.
+      #
+      # RESIZE: convert is the image resize ENGINE for the WHOLE Output op (both
+      # routes) — the compress optimiser has NO resize code (it never reads
+      # width/height/fit). The API carries width/height/fit onto the convert op
+      # for BOTH arms: format_change = convert to the requested format; same_format
+      # = convert to the SAME format token (the optimiser leg delegates resize to
+      # the transcoder — see compress.image resize comments). So width/height/fit
+      # are declared HERE (the worker reads them: image_convert.rs ->
+      # shared::image::resize_request_from_job, full validation + 16MP cap + svg
+      # REJECT + animation preserve; live #257). svg INPUT cannot be raster-resized
+      # (worker rejects as invalid_options) — the output-keyed projection lists
+      # resize on every format_change target, so it is INPUT-GATED: consumers
+      # cross-ref same_format[input] (svg has no resize) before offering it.
+      max_output_pixels: 16000000          # worker MAX_OUTPUT_PIXELS; parity with compress.image
       options:
         output_format:
           type: enum
@@ -60,6 +78,67 @@ operation:
             (e.g. `magenta`) to the white default, so the `pattern` rejects a
             non-hex value as `invalid_options` rather than advertising an inert
             free-form string (e2e staging-verified 2026-06-22).
+        width:
+          type: integer
+          min: 1
+          max: 16384
+          honored_on: [format_change]
+          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 — see the resize comment above.
+        height:
+          type: integer
+          min: 1
+          max: 16384
+          honored_on: [format_change]
+          description: "Resize-inside-Output: target height in pixels (1-16384; width*height <= max_output_pixels). Not honored for SVG input. See `width`."
+        fit:
+          type: enum
+          values: [max, crop, scale]
+          default: max
+          depends_on: { width: set, height: set, logic: or }
+          honored_on: [format_change]
+          description: >-
+            Resize mode. `max` (default) = fit within bounds, preserving aspect ratio
+            and NEVER upscaling — it caps at the source dimensions. This IS the
+            "no-enlarge" behaviour (there is no separate `no_enlarge` flag — the
+            worker has no such key). `crop`/`scale` = exact dimensions (`scale`
+            deliberately enlarges past source). Applies only when width or height is set.
+
+    # svg is VECTOR: it converts (rasterises) to a raster format, but CANNOT be
+    # raster-resized — the convert worker rejects svg resize. Split out of
+    # convert.image so width/height/fit are STRUCTURALLY absent for svg input:
+    # the API validates an svg op against THIS group + rejects resize at create
+    # (not prose), and raw schema / availability / accepted-options never
+    # advertise svg resize. Mirrors compress.image_svg. NO resize, NO area cap.
+    image_svg:
+      mimes:
+        - image/svg+xml
+      options:
+        output_format:
+          type: enum
+          values: [jpeg, png, webp, avif, gif, tiff]
+          required: true
+          description: "Target raster format (SVG is rasterised, then encoded)."
+        quality:
+          type: integer
+          min: 1
+          max: 100
+          default: 85
+          depends_on: { output_format: [jpeg, webp, avif] }
+          honored_on: [format_change]
+          description: "Output quality for lossy formats"
+        background:
+          type: string
+          pattern: "^#[0-9a-fA-F]{6}$"
+          depends_on: { output_format: jpeg }
+          honored_on: [format_change]
+          description: >-
+            Background colour as a 6-digit hex (`#RRGGBB`) for transparent SVG
+            rasterised to JPEG (alpha-flatten). HEX ONLY — non-hex is rejected as
+            `invalid_options` (see convert.image.background).
 
     video:
       mimes:

package/package.json

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