@giveitsmaller/contracts 0.33.0 → 0.34.0

package/operations/schemas/compress.yaml

@@ -33,28 +33,69 @@ operation:
     # dangling coming-soon values are dishonest at source; every other format
     # change is the convert operation's job (all stable). Re-add a target here
     # only when its compress+format canonicalization actually ships.
+    #
+    # ---- ROUTE-AWARE "OUTPUT" model (image-options Phase 0, tewB37Jg) ----
+    # The user-facing "Output" operation IS this compress op + output_format:
+    # the API routes by comparing the authored/resolved output_format to the
+    # input format — same_format (output_format == input, or `original`) runs
+    # the libcaesium OPTIMISER; format_change runs the convert TRANSCODER (the
+    # VcPeRWdD facade). Each option carries `honored_on: [<route>...]` declaring
+    # which route's worker reads it (absent ≡ all routes its depends_on admits;
+    # 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.
+    #
+    # The remaining PHASE 1 controls land availability:planned (ANTI-REGRESSION:
+    # no stable-flip until the worker honours it + API proves representability —
+    # plan §2.5; FE-hidden / API-422 until then). They are route-CONDITIONAL,
+    # which is why they ride the route-aware honored_on model:
+    #   lossless (jpeg/webp)  -> the worker `lossless` bool the API has never
+    #     emitted (product-parked); planned, optimiser (same_format) route only.
+    #   metadata: keep        -> un-hardcode keep_metadata=false; planned value
+    #     on the existing `metadata` enum.
+    #   lossy (png)           -> palette quantization (pngquant/imagequant-class);
+    #     planned + licensing-gated by the lambdas spike — do NOT stable-flip
+    #     until that confirms a permissive path.
     image_jpeg:
       mimes:
         - image/jpeg
+      # Resize-inside-Output (planned) shares thumbnail-image's 16MP output-area
+      # wall — the per-axis 16384 cap can't express it (FORMAT.md §max_output_pixels).
+      max_output_pixels: 16000000
       options:
         quality:
           type: integer
           min: 1
           max: 100
           default: 80
+          honored_on: [same_format]
           description: "Compression quality (1 = smallest file, 100 = best quality)."
         metadata:
           type: enum
-          values: [all]
+          values: [all, keep]
           default: all
+          per_value_availability:
+            keep: { availability: planned }
+          honored_on: [same_format]
           description: >-
-            Metadata handling. `all` = strip all EXIF/IPTC/XMP — the only supported
-            behaviour (the compress worker always strips; preservation is not
-            currently available).
+            Metadata handling. `all` = strip all EXIF/IPTC/XMP (default, the only
+            live behaviour — the compress worker hardcodes keep_metadata=false).
+            `keep` = preserve metadata — `planned` (the worker cannot preserve it
+            yet; un-hardcoding keep_metadata is the Phase 1 keep/strip toggle).
+            Optimiser (same_format) route — the format-change transcoder has no
+            metadata-preservation control today.
         progressive:
           type: boolean
           default: true
-          description: "Enable progressive JPEG rendering (a low-quality preview renders first, then refines). JPEG only."
+          honored_on: [same_format]
+          description: "Enable progressive JPEG rendering (a low-quality preview renders first, then refines). JPEG only — the optimiser (same_format) route."
         output_format:
           type: enum
           values: [original, webp]
@@ -64,31 +105,76 @@ operation:
             WebP — the one live compress+format target (proven on staging). Other format
             changes (jpeg/png/avif/gif/tiff) are the convert operation's job, not compress.
             See FORMAT.md.
+        lossless:
+          type: boolean
+          default: false
+          availability: planned
+          honored_on: [same_format]
+          description: >-
+            Encode losslessly (JPEG optimiser path). `planned` — the worker carries
+            a `lossless` bool the API has never emitted (product-parked: a lossless
+            output can be LARGER than lossy). Optimiser (same_format) route only.
+        width:
+          type: integer
+          min: 1
+          max: 16384
+          honored_on: [same_format, format_change]
+          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.
+            Optional; omit to keep the source dimensions.
+        height:
+          type: integer
+          min: 1
+          max: 16384
+          honored_on: [same_format, format_change]
+          description: "Resize-inside-Output: target height in pixels (1-16384; width*height <= max_output_pixels). Resize replaces the image (one output). Optional — see `width`."
+        fit:
+          type: enum
+          values: [max, crop, scale]
+          default: max
+          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.
 
     image_png:
       mimes:
         - image/png
+      max_output_pixels: 16000000
       options:
         quality:
           type: integer
           min: 1
           max: 100
           default: 80
+          honored_on: [same_format]
           description: "Compression quality (1 = smallest file, 100 = best quality)."
         metadata:
           type: enum
-          values: [all]
+          values: [all, keep]
           default: all
+          per_value_availability:
+            keep: { availability: planned }
+          honored_on: [same_format]
           description: >-
-            Metadata handling. `all` = strip all EXIF/IPTC/XMP — the only supported
-            behaviour (the compress worker always strips; preservation is not
-            currently available).
+            Metadata handling. `all` = strip all EXIF/IPTC/XMP (default, the only
+            live behaviour — the compress worker hardcodes keep_metadata=false).
+            `keep` = preserve metadata — `planned` (the worker cannot preserve it
+            yet; un-hardcoding keep_metadata is the Phase 1 keep/strip toggle).
+            Optimiser (same_format) route — the format-change transcoder has no
+            metadata-preservation control today.
         optimization_level:
           type: integer
           min: 0
           max: 6
           default: 3
-          description: "PNG optimization effort (0-6, oxipng). Higher = smaller file, slower encode. Default 3."
+          honored_on: [same_format]
+          description: "PNG optimization effort (0-6, oxipng). Higher = smaller file, slower encode. Default 3. Optimiser (same_format) route."
         output_format:
           type: enum
           values: [original, webp]
@@ -98,6 +184,44 @@ operation:
             WebP — the one live compress+format target (proven on staging). Other format
             changes (jpeg/png/avif/gif/tiff) are the convert operation's job, not compress.
             See FORMAT.md.
+        lossy:
+          type: boolean
+          default: false
+          availability: planned
+          honored_on: [same_format]
+          description: >-
+            Lossy PNG palette quantization (pngquant/imagequant-class) — a large
+            saving for flat-colour PNGs. `planned` AND LICENSING-GATED: do not
+            stable-flip until the lambdas licensing spike confirms a permissive
+            quantizer path (libimagequant/pngquant is GPL-or-commercial). Optimiser
+            (same_format) route only.
+        width:
+          type: integer
+          min: 1
+          max: 16384
+          honored_on: [same_format, format_change]
+          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.
+            Optional; omit to keep the source dimensions.
+        height:
+          type: integer
+          min: 1
+          max: 16384
+          honored_on: [same_format, format_change]
+          description: "Resize-inside-Output: target height in pixels (1-16384; width*height <= max_output_pixels). Resize replaces the image (one output). Optional — see `width`."
+        fit:
+          type: enum
+          values: [max, crop, scale]
+          default: max
+          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.
 
     image_avif:
       availability: beta
@@ -112,27 +236,36 @@ operation:
       # contract vocab today; tracked for the image-size-cap mechanism (F3).
       mimes:
         - image/avif
+      max_output_pixels: 16000000
       options:
         quality:
           type: integer
           min: 1
           max: 100
           default: 80
+          honored_on: [same_format]
           description: "Compression quality (1 = smallest file, 100 = best quality)."
         metadata:
           type: enum
-          values: [all]
+          values: [all, keep]
           default: all
+          per_value_availability:
+            keep: { availability: planned }
+          honored_on: [same_format]
           description: >-
-            Metadata handling. `all` = strip all EXIF/IPTC/XMP — the only supported
-            behaviour (the compress worker always strips; preservation is not
-            currently available).
+            Metadata handling. `all` = strip all EXIF/IPTC/XMP (default, the only
+            live behaviour — the compress worker hardcodes keep_metadata=false).
+            `keep` = preserve metadata — `planned` (the worker cannot preserve it
+            yet; un-hardcoding keep_metadata is the Phase 1 keep/strip toggle).
+            Optimiser (same_format) route — the format-change transcoder has no
+            metadata-preservation control today.
         avif_speed:
           type: integer
           min: 1
           max: 10
           default: 4
-          description: "AVIF encode speed (1-10, ravif). Lower = smaller file, slower encode; higher = faster, larger. Default 4."
+          honored_on: [same_format]
+          description: "AVIF encode speed (1-10, ravif). Lower = smaller file, slower encode; higher = faster, larger. Default 4. Optimiser (same_format) route."
         output_format:
           type: enum
           values: [original, webp]
@@ -142,30 +275,174 @@ operation:
             WebP — the one live compress+format target (proven on staging). Other format
             changes (jpeg/png/avif/gif/tiff) are the convert operation's job, not compress.
             See FORMAT.md.
+        width:
+          type: integer
+          min: 1
+          max: 16384
+          honored_on: [same_format, format_change]
+          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.
+            Optional; omit to keep the source dimensions.
+        height:
+          type: integer
+          min: 1
+          max: 16384
+          honored_on: [same_format, format_change]
+          description: "Resize-inside-Output: target height in pixels (1-16384; width*height <= max_output_pixels). Resize replaces the image (one output). Optional — see `width`."
+        fit:
+          type: enum
+          values: [max, crop, scale]
+          default: max
+          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.
 
-    image:
+    # 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
+    # `lossless` knob. gif/tiff (below) resize but have no lossless; svg is vector
+    # (no raster resize, no lossless) — see image_svg.
+    image_webp:
       mimes:
         - image/webp
-        - image/gif
+      max_output_pixels: 16000000
+      options:
+        quality:
+          type: integer
+          min: 1
+          max: 100
+          default: 80
+          honored_on: [same_format]
+          description: "Compression quality (1 = smallest file, 100 = best quality)."
+        metadata:
+          type: enum
+          values: [all, keep]
+          default: all
+          per_value_availability:
+            keep: { availability: planned }
+          honored_on: [same_format]
+          description: >-
+            Metadata handling. `all` = strip all EXIF/IPTC/XMP (default, the only
+            live behaviour — the compress worker hardcodes keep_metadata=false).
+            `keep` = preserve metadata — `planned` (the worker cannot preserve it
+            yet; un-hardcoding keep_metadata is the Phase 1 keep/strip toggle).
+            Optimiser (same_format) route — the format-change transcoder has no
+            metadata-preservation control today.
+        output_format:
+          type: enum
+          values: [original, webp]
+          default: original
+          description: >-
+            Output format. original = keep input format (default); webp = recompress to
+            WebP — the one live compress+format target (proven on staging). Other format
+            changes (jpeg/png/avif/gif/tiff) are the convert operation's job, not compress.
+            See FORMAT.md.
+        lossless:
+          type: boolean
+          default: false
+          availability: planned
+          honored_on: [same_format]
+          description: >-
+            Encode WebP losslessly (optimiser path). `planned` — the worker carries a
+            `lossless` bool the API has never emitted (product-parked: lossless can be
+            LARGER). Optimiser (same_format) route only.
+        width:
+          type: integer
+          min: 1
+          max: 16384
+          honored_on: [same_format, format_change]
+          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.
+            Optional; omit to keep the source dimensions.
+        height:
+          type: integer
+          min: 1
+          max: 16384
+          honored_on: [same_format, format_change]
+          description: "Resize-inside-Output: target height in pixels (1-16384; width*height <= max_output_pixels). Resize replaces the image (one output). Optional — see `width`."
+        fit:
+          type: enum
+          values: [max, crop, scale]
+          default: max
+          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.
+
+    # 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
+    # quality/metadata/output_format carry. NO Resize / lossless / area cap here.
+    image_svg:
+      mimes:
         - image/svg+xml
+      options:
+        quality:
+          type: integer
+          min: 1
+          max: 100
+          default: 80
+          honored_on: [same_format]
+          description: "Compression quality (1 = smallest file, 100 = best quality)."
+        metadata:
+          type: enum
+          values: [all, keep]
+          default: all
+          per_value_availability:
+            keep: { availability: planned }
+          honored_on: [same_format]
+          description: >-
+            Metadata handling. `all` = strip all metadata (default, live). `keep` =
+            preserve metadata — `planned` (worker cannot preserve yet). Optimiser
+            (same_format) route.
+        output_format:
+          type: enum
+          values: [original, webp]
+          default: original
+          description: >-
+            Output format. original = keep input format (default); webp = recompress to
+            WebP. Other format changes are the convert operation's job. See FORMAT.md.
+
+    # gif/tiff: raster Resize is engine-proven (both are in thumbnail-images), but
+    # the optimiser `lossless` knob is WebP-only — not advertised here.
+    image:
+      mimes:
+        - image/gif
         - image/tiff
+      max_output_pixels: 16000000
       options:
         quality:
           type: integer
           min: 1
           max: 100
           default: 80
+          honored_on: [same_format]
           description: >-
             Compression quality (1 = smallest file, 100 = best quality). For animated
             GIF the worker honours this but real-world size reduction is typically small.
         metadata:
           type: enum
-          values: [all]
+          values: [all, keep]
           default: all
+          per_value_availability:
+            keep: { availability: planned }
+          honored_on: [same_format]
           description: >-
-            Metadata handling. `all` = strip all EXIF/IPTC/XMP — the only supported
-            behaviour (the compress worker always strips; preservation is not
-            currently available).
+            Metadata handling. `all` = strip all EXIF/IPTC/XMP (default, the only
+            live behaviour — the compress worker hardcodes keep_metadata=false).
+            `keep` = preserve metadata — `planned` (the worker cannot preserve it
+            yet; un-hardcoding keep_metadata is the Phase 1 keep/strip toggle).
+            Optimiser (same_format) route — the format-change transcoder has no
+            metadata-preservation control today.
         output_format:
           type: enum
           values: [original, webp]
@@ -175,6 +452,33 @@ operation:
             WebP — the one live compress+format target (proven on staging). Other format
             changes (jpeg/png/avif/gif/tiff) are the convert operation's job, not compress.
             See FORMAT.md.
+        width:
+          type: integer
+          min: 1
+          max: 16384
+          honored_on: [same_format, format_change]
+          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.
+            Optional; omit to keep the source dimensions.
+        height:
+          type: integer
+          min: 1
+          max: 16384
+          honored_on: [same_format, format_change]
+          description: "Resize-inside-Output: target height in pixels (1-16384; width*height <= max_output_pixels). Resize replaces the image (one output). Optional — see `width`."
+        fit:
+          type: enum
+          values: [max, crop, scale]
+          default: max
+          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.
 
     audio:
       mimes:

package/operations/schemas/convert.yaml

@@ -26,6 +26,13 @@ operation:
         # (avif is also a valid OUTPUT via output_format — ravif encode.)
         image/avif: { availability: beta }
         image/heic: { availability: beta }
+      # convert.image is the TRANSCODER leg of the route-aware image "Output"
+      # model (FORMAT.md §"Route-aware Output model"): a format_change Output
+      # route (output_format != input) runs here. Its options carry
+      # `honored_on: [format_change]` so the merged per-(media, route,
+      # 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.
       options:
         output_format:
           type: enum
@@ -38,11 +45,13 @@ operation:
           max: 100
           default: 85
           depends_on: { output_format: [jpeg, webp, avif] }
+          honored_on: [format_change]
           description: "Output quality for lossy formats"
         background:
           type: string
           depends_on: { output_format: jpeg }
-          description: "Background colour (hex, e.g. '#ffffff') for transparent images converted to JPEG"
+          honored_on: [format_change]
+          description: "Background colour (hex, e.g. '#ffffff') for transparent images converted to JPEG (the format-change→JPEG alpha-flatten — Output's transparency fill control)."
 
     video:
       mimes:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@giveitsmaller/contracts",
-  "version": "0.33.0",
+  "version": "0.34.0",
   "description": "Generated contract types for GISL (Give It Smaller)",
   "license": "MIT",
   "type": "module",
@@ -27,6 +27,7 @@
     "./asyncapi/events.yaml": "./asyncapi/events.yaml",
     "./availability/availability.json": "./availability/availability.json",
     "./accepted-options/accepted-options.json": "./accepted-options/accepted-options.json",
+    "./accepted-options/image-output-routes.json": "./accepted-options/image-output-routes.json",
     "./operation-capabilities/operation-capabilities.json": "./operation-capabilities/operation-capabilities.json",
     "./operations/schemas/archive.yaml": "./operations/schemas/archive.yaml",
     "./operations/schemas/audio_overlay.yaml": "./operations/schemas/audio_overlay.yaml",
@@ -52,6 +53,7 @@
     "operations/schemas/",
     "availability/availability.json",
     "accepted-options/accepted-options.json",
+    "accepted-options/image-output-routes.json",
     "operation-capabilities/operation-capabilities.json"
   ],
   "scripts": {