@giveitsmaller/contracts 0.35.0 → 0.37.0

package/operations/schemas/convert.yaml

@@ -8,12 +8,17 @@ operation:
 
   mime_groups:
     image:
+      # svg is split into convert.image_svg + gif into convert.image_gif (below).
+      # svg rasterises but CANNOT be raster-resized (worker rejects svg resize), so
+      # it must NOT sit in a group that declares width/height/fit. gif is split out
+      # because it ALSO targets VIDEO (mp4/webm — the GIF→video transcode, card
+      # oEjNe9gT), which a jpeg/png input must not advertise. This `image` group is
+      # the still-raster inputs whose only targets are still-image formats. Mirrors
+      # compress.image_svg / compress.image* per-format split.
       mimes:
         - image/jpeg
         - image/png
-        - image/gif
         - image/webp
-        - image/svg+xml
         - image/tiff
         - image/bmp
         - image/vnd.microsoft.icon
@@ -33,6 +38,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 +79,175 @@ 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).
+        metadata:
+          type: enum
+          values: [strip, keep]
+          default: strip
+          availability: planned
+          honored_on: [format_change]
+          description: >-
+            Metadata handling on the format-change (convert/transcoder) route.
+            `strip` = remove all EXIF/IPTC/XMP (default), `keep` = preserve. `planned`
+            — the convert worker re-encodes from pixels and does not yet preserve
+            metadata across a format change, so the API returns feature_not_available
+            (rather than "Unknown option" on a format-change request — e2e/api flagged
+            2026-06-23). This is a new (planned) surface, so it carries no deprecated
+            `all` alias — unlike compress.image.metadata, which keeps `all` for its
+            existing callers. Stable-flip gated on lambdas proving convert-route
+            metadata preservation; the honoured target subset may narrow (avif/heic
+            targets re-encode and cannot keep).
+        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).
+
+    # gif is animated raster: it converts to a STILL image (first frame / rasterise —
+    # the existing image targets, stable) AND — NEW, planned — to VIDEO (mp4/webm):
+    # the GIF→video transcode (animated GIF → muted, play-once video; ~85-95% smaller
+    # than the GIF; card oEjNe9gT). Split out of convert.image so ONLY gif advertises
+    # the mp4/webm video targets (a jpeg/png input must not show them). The output
+    # crosses the media boundary image→video; per codex convergence this stays
+    # operation_type=convert (the convert worker's video_convert path owns the ffmpeg
+    # mp4/webm encode — NOT a new op, NOT the compression-video worker). mp4/webm are
+    # per_value_availability:planned and flip INDEPENDENTLY (like target_size's
+    # per-format flip) on lambdas worker-proof + API representability + the API's
+    # output-aware billing override (convert.image_gif→video is video-class encode
+    # work, NOT a cheap image transcode — the API must not price it as convert.image;
+    # API owns that, ticket 0Z4zunCr). Planned-first anti-regression (image-options §2.5).
+    image_gif:
+      mimes:
+        - image/gif
+      max_output_pixels: 16000000
+      options:
+        output_format:
+          type: enum
+          values: [jpeg, png, webp, avif, gif, tiff, mp4, webm]
+          required: true
+          per_value_availability:
+            mp4:  { availability: planned }
+            webm: { availability: planned }
+          description: >-
+            Target format. The still-image targets (jpeg/png/webp/avif/gif/tiff) take
+            the first frame / rasterise (stable, today's gif-convert behaviour). `mp4`
+            / `webm` are the NEW (planned) GIF→VIDEO transcode targets — the animated
+            GIF becomes a muted, play-once video (`mp4` = H.264 / yuv420p / +faststart,
+            plays everywhere; `webm` = VP9, smaller). GIFs are silent (no audio
+            stream); the GIF infinite-loop becomes a playback attribute (`<video loop>`)
+            the player sets, NOT baked into the file. mp4 and webm flip planned→stable
+            independently on worker proof.
+        quality:
+          type: integer
+          min: 1
+          max: 100
+          default: 85
+          depends_on: { output_format: [jpeg, webp, avif] }
+          honored_on: [format_change]
+          description: >-
+            Output quality for the lossy STILL-IMAGE targets (jpeg/webp/avif). The
+            video targets (mp4/webm) use a sensible default encode quality in v1 —
+            there is no exposed CRF knob yet (planned-first; may be added later).
+        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 a transparent GIF
+            flattened to JPEG (alpha-flatten). HEX ONLY — non-hex is rejected as
+            `invalid_options` (see convert.image.background).
+        metadata:
+          type: enum
+          values: [strip, keep]
+          default: strip
+          availability: planned
+          honored_on: [format_change]
+          description: >-
+            Metadata handling on the format-change route (still-image targets).
+            `planned` — mirrors convert.image.metadata (the convert worker does not
+            yet preserve metadata across a format change). The video targets carry no
+            EXIF/IPTC/XMP.
+        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). Applies to the still-image targets; for the planned
+            mp4/webm video targets, resize applicability is settled at the worker flip.
+        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). 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; `crop`/`scale` = exact dimensions. Applies only when
+            width or height is set.
 
     video:
       mimes:

package/package.json

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