@giveitsmaller/sdk 0.15.0 → 0.17.0

package/dist/ergonomic/option_types.js

@@ -0,0 +1,57 @@
+/**
+ * Typed per-op option interfaces for the ergonomic verbs (card Dhje3Faq).
+ * These replace the untyped `Record<string, unknown>` bags so the IDE can offer
+ * key completion and `tsc` rejects typos. The KEY SET of each interface is pinned
+ * to the contract two ways: (1) the source-level `Equal<...>` assertions below tie
+ * each interface to its `*_OPTION_KEYS` tuple at `tsc` time; (2) the wire-key
+ * conformance guard ties each tuple (∪ positional-owned) to the generated
+ * `OperationMetadata` at test time. Value types are best-effort (per-value/enum
+ * sync is out of scope — keys are the contract anchor).
+ *
+ * Keys a verb owns via a positional argument are EXCLUDED from its interface
+ * (`output_format` on convert, `text` on textWatermark) — they are set by the
+ * first argument and rejected if supplied in the bag (see `option_validation.ts`).
+ *
+ * Mirrored by the PHP array-shape docblocks — keep in lockstep.
+ */
+const CONVERT_OPTION_KEYS = [
+    'quality', 'background', 'crf', 'trim_start', 'trim_end', 'fps', 'width',
+    'max_colors', 'loop', 'dither', 'bitrate', 'pages', 'dpi',
+];
+const THUMBNAIL_OPTION_KEYS = [
+    'width', 'height', 'fit', 'format', 'quality', 'timestamp', 'source', 'page',
+];
+const TEXT_WATERMARK_OPTION_KEYS = [
+    'font_size', 'color', 'font_family', 'rotation', 'watermark_mode',
+    'tile_spacing', 'anchor', 'margin_x', 'margin_y', 'opacity',
+];
+const WATERMARK_OPTION_KEYS = [
+    'anchor', 'margin_x', 'margin_y', 'opacity', 'overlay_width',
+];
+const OUTPUT_OPTION_KEYS = [
+    'quality', 'width', 'height', 'fit', 'background', 'progressive',
+    'optimization_level', 'avif_speed', 'metadata', 'lossless', 'lossy',
+];
+const _convertKeysMatch = true;
+const _thumbnailKeysMatch = true;
+const _textWatermarkKeysMatch = true;
+const _watermarkKeysMatch = true;
+const _outputKeysMatch = true;
+// Reference the assertions so `noUnusedLocals` doesn't strip them.
+void _convertKeysMatch;
+void _thumbnailKeysMatch;
+void _textWatermarkKeysMatch;
+void _watermarkKeysMatch;
+void _outputKeysMatch;
+/**
+ * The user-supplyable option keys per verb (excludes positional-owned keys).
+ * Exported for the wire-key conformance guard, which asserts each tuple ∪ its
+ * positional-owned keys equals the contract `operationOptionKeys(metadata)`.
+ */
+export const VERB_OPTION_KEYS = {
+    convert: CONVERT_OPTION_KEYS,
+    thumbnail: THUMBNAIL_OPTION_KEYS,
+    textWatermark: TEXT_WATERMARK_OPTION_KEYS,
+    watermark: WATERMARK_OPTION_KEYS,
+    output: OUTPUT_OPTION_KEYS,
+};

package/dist/ergonomic/option_validation.d.ts

@@ -0,0 +1,58 @@
+import { type OperationMetadata } from '@giveitsmaller/contracts/operations';
+/**
+ * Eager, synchronous, PRE-UPLOAD option-key validation for the ergonomic verbs
+ * (card Dhje3Faq). The file-first builders accept verb options as untyped bags;
+ * a user typo (`{ quaity: 80 }`) would otherwise flow to the server and 422.
+ * This module rejects unknown keys at the verb call — before any upload —
+ * mirroring the existing `compress()` optimize-check and the watermark eager
+ * gate. The allowed key set is read from the generated `OperationMetadata`
+ * sidecars (the same contract-anchored source the wire-key conformance guard
+ * uses), so it can never silently drift from the contract.
+ *
+ * SCOPE: `convert` / `thumbnail` / `textWatermark` / `watermark` only. `compress`
+ * is deliberately EXCLUDED — its bag legitimately carries SDK-only keys
+ * (`optimize`, `presetOverrides`) and camelCase resolver aliases (`targetSize`,
+ * `outputFormat`) that are not `operationOptionKeys(compressMetadata)`; it has its
+ * own `unknown_field` validation through the preset resolver.
+ *
+ * Mirrored by the PHP `OptionValidation` helper — keep the two in lockstep.
+ */
+/**
+ * OPERATION-LEVEL contract option keys (the keys valid in `OperationDef.options`):
+ * the union of every mime group's `options` plus `direct_options` for
+ * media-agnostic ops. Deliberately EXCLUDES `per_input_options` (valid only on a
+ * merge input). Promoted from the wire-key conformance guard for runtime reuse.
+ */
+export declare function operationOptionKeys(metadata: OperationMetadata): ReadonlySet<string>;
+/** The ergonomic verbs whose option bags this module key-validates. */
+export type ValidatedVerb = 'convert' | 'thumbnail' | 'textWatermark' | 'watermark' | 'output';
+/** Accessor for the conformance guard (pins these sets to the contract metadata). */
+export declare function allowedKeysFor(verb: ValidatedVerb): ReadonlySet<string>;
+/**
+ * Validate a USER-supplied options bag for an ergonomic verb. Throws
+ * {@link GislConfigError} (reason `unknown_field`) synchronously, BEFORE any
+ * upload or wire-key injection. Call this at the TOP of every verb body, before
+ * the `format`-drop / `output_format` / `text` injection.
+ *
+ * @throws {GislConfigError} reason `unknown_field` when the bag carries a key the
+ *   verb owns via a positional argument, or a key absent from the op's contract
+ *   option set.
+ */
+export declare function validateVerbOptions(verb: ValidatedVerb, options: object | null | undefined): void;
+/**
+ * Assert thumbnail `width` AND `height` are both present and non-nullish (the
+ * contract marks both `required` for image/video/document). The typed signature
+ * already enforces this at compile time; this RUNTIME guard catches JS callers and
+ * an explicit `undefined`/`null` BEFORE upload. Rejecting `null` (not just
+ * `undefined`) keeps TS in lockstep with the PHP `assertThumbnailDimensions`, which
+ * must reject `null` because PHP drops null values pre-lower — so a `null` dimension
+ * is a pre-upload error in BOTH languages, never a wire `null` that 422s. Mirrored
+ * in PHP.
+ *
+ * @throws {GislConfigError} reason `missing_required_field` naming the absent
+ *   dimension(s) in `conflictingFields`.
+ */
+export declare function assertThumbnailDimensions(options: {
+    width?: unknown;
+    height?: unknown;
+} | null | undefined): void;

package/dist/ergonomic/option_validation.js

@@ -0,0 +1,143 @@
+import { convertMetadata, thumbnailMetadata, textWatermarkMetadata, imageWatermarkMetadata, videoWatermarkMetadata, } from '@giveitsmaller/contracts/operations';
+import { GislConfigError } from '../errors.js';
+import { VERB_OPTION_KEYS } from './option_types.js';
+/**
+ * Eager, synchronous, PRE-UPLOAD option-key validation for the ergonomic verbs
+ * (card Dhje3Faq). The file-first builders accept verb options as untyped bags;
+ * a user typo (`{ quaity: 80 }`) would otherwise flow to the server and 422.
+ * This module rejects unknown keys at the verb call — before any upload —
+ * mirroring the existing `compress()` optimize-check and the watermark eager
+ * gate. The allowed key set is read from the generated `OperationMetadata`
+ * sidecars (the same contract-anchored source the wire-key conformance guard
+ * uses), so it can never silently drift from the contract.
+ *
+ * SCOPE: `convert` / `thumbnail` / `textWatermark` / `watermark` only. `compress`
+ * is deliberately EXCLUDED — its bag legitimately carries SDK-only keys
+ * (`optimize`, `presetOverrides`) and camelCase resolver aliases (`targetSize`,
+ * `outputFormat`) that are not `operationOptionKeys(compressMetadata)`; it has its
+ * own `unknown_field` validation through the preset resolver.
+ *
+ * Mirrored by the PHP `OptionValidation` helper — keep the two in lockstep.
+ */
+/**
+ * OPERATION-LEVEL contract option keys (the keys valid in `OperationDef.options`):
+ * the union of every mime group's `options` plus `direct_options` for
+ * media-agnostic ops. Deliberately EXCLUDES `per_input_options` (valid only on a
+ * merge input). Promoted from the wire-key conformance guard for runtime reuse.
+ */
+export function operationOptionKeys(metadata) {
+    const keys = new Set();
+    for (const group of Object.values(metadata.mime_groups)) {
+        for (const k of Object.keys(group.options))
+            keys.add(k);
+    }
+    for (const k of Object.keys(metadata.direct_options ?? {}))
+        keys.add(k);
+    return keys;
+}
+function union(...sets) {
+    const out = new Set();
+    for (const set of sets)
+        for (const k of set)
+            out.add(k);
+    return out;
+}
+/**
+ * The contract option-key set per validated verb (the GENERIC allowed set).
+ * `watermark` is the UNION of `image_watermark` + `video_watermark` because the
+ * base media may be undetectable at the `.watermark()` call; the existing
+ * media-routing gate still rejects the wrong route by media.
+ */
+const ALLOWED_KEYS = {
+    convert: operationOptionKeys(convertMetadata),
+    thumbnail: operationOptionKeys(thumbnailMetadata),
+    textWatermark: operationOptionKeys(textWatermarkMetadata),
+    watermark: union(operationOptionKeys(imageWatermarkMetadata), operationOptionKeys(videoWatermarkMetadata)),
+    // `output` is the image Output facade — its allowed keys are the UNION of every
+    // image route's honored+planned options (the image-output-routes projection),
+    // INCLUDING `output_format` (in every cell's honored set) which — like `convert`
+    // — is in the allowed set but rejected first by the positional-owned guard. This
+    // is the COARSE static gate (reject keys no image route ever honors, e.g. a video
+    // `crf`); the precise per-route honored/planned narrowing happens in the
+    // `output()` lowering (`resolveOutputRoute`). Pinned to the projection union by
+    // the output-route conformance test.
+    output: new Set([...VERB_OPTION_KEYS.output, 'output_format']),
+};
+/**
+ * Keys a verb OWNS via a positional argument: a user must not also supply them
+ * in the options bag (they would be silently overridden by the positional). The
+ * guard runs BEFORE the generic check so these get a specific, actionable
+ * message rather than the generic "unknown option" one. `format` is an SDK alias
+ * for the positional (not a contract key) and is owned too.
+ */
+const POSITIONAL_OWNED = {
+    convert: ['output_format', 'format'],
+    textWatermark: ['text'],
+    // `output(format, …)` sets the target format via its first argument; the wire
+    // key `output_format` and the SDK alias `format` must not be supplied in the bag.
+    output: ['output_format', 'format'],
+};
+/** Accessor for the conformance guard (pins these sets to the contract metadata). */
+export function allowedKeysFor(verb) {
+    return ALLOWED_KEYS[verb];
+}
+/**
+ * Validate a USER-supplied options bag for an ergonomic verb. Throws
+ * {@link GislConfigError} (reason `unknown_field`) synchronously, BEFORE any
+ * upload or wire-key injection. Call this at the TOP of every verb body, before
+ * the `format`-drop / `output_format` / `text` injection.
+ *
+ * @throws {GislConfigError} reason `unknown_field` when the bag carries a key the
+ *   verb owns via a positional argument, or a key absent from the op's contract
+ *   option set.
+ */
+export function validateVerbOptions(verb, options) {
+    // The typed signatures require an options object, but an untyped JS caller can
+    // still omit it (e.g. `thumbnail()` — which dropped its `= {}` default when
+    // width/height became required). A nullish bag has no keys to reject; the
+    // separate `assertThumbnailDimensions` then reports the missing dimensions as a
+    // clean GislConfigError rather than a raw TypeError.
+    if (options === null || options === undefined)
+        return;
+    const owned = POSITIONAL_OWNED[verb];
+    if (owned !== undefined) {
+        for (const key of owned) {
+            if (Object.prototype.hasOwnProperty.call(options, key)) {
+                const arg = verb === 'textWatermark' ? 'text' : 'output format';
+                throw new GislConfigError(`${verb}() sets the ${arg} via its first argument; remove '${key}' from the options bag.`, { reason: 'unknown_field', conflictingFields: [key] });
+            }
+        }
+    }
+    const allowed = ALLOWED_KEYS[verb];
+    for (const key of Object.keys(options)) {
+        if (!allowed.has(key)) {
+            throw new GislConfigError(`${verb}: unknown option '${key}'. Valid options: ${[...allowed].sort().join(', ')}.`, { reason: 'unknown_field', conflictingFields: [key] });
+        }
+    }
+}
+/**
+ * Assert thumbnail `width` AND `height` are both present and non-nullish (the
+ * contract marks both `required` for image/video/document). The typed signature
+ * already enforces this at compile time; this RUNTIME guard catches JS callers and
+ * an explicit `undefined`/`null` BEFORE upload. Rejecting `null` (not just
+ * `undefined`) keeps TS in lockstep with the PHP `assertThumbnailDimensions`, which
+ * must reject `null` because PHP drops null values pre-lower — so a `null` dimension
+ * is a pre-upload error in BOTH languages, never a wire `null` that 422s. Mirrored
+ * in PHP.
+ *
+ * @throws {GislConfigError} reason `missing_required_field` naming the absent
+ *   dimension(s) in `conflictingFields`.
+ */
+export function assertThumbnailDimensions(options) {
+    // Null-safe so an untyped JS `thumbnail()` (no args, no default) reports both
+    // dimensions missing as a clean GislConfigError instead of a raw TypeError.
+    const o = options ?? {};
+    const missing = [];
+    if (o.width === undefined || o.width === null)
+        missing.push('width');
+    if (o.height === undefined || o.height === null)
+        missing.push('height');
+    if (missing.length > 0) {
+        throw new GislConfigError(`thumbnail requires both width and height (the contract marks both required); missing: ${missing.join(', ')}.`, { reason: 'missing_required_field', conflictingFields: missing });
+    }
+}

package/dist/ergonomic/preset_resolver.d.ts

@@ -2,13 +2,14 @@ import type { ResolvedOptions } from '../builder.js';
 import type { OptimizeFor } from '../generated/sdk_spec/enums.js';
 import { type PresetDefaults, type PresetMedia, type PresetOp } from './presets/index.js';
 /**
- * Bumped on any change to a `*PresetOptions.shippedDefaultsFor(...)` cell value.
- * Must track the contracts `sdk-spec/version.yaml` `presetVersion` (mirrored in
- * the generated `sdk_spec/version.ts`). 1.0 → 1.2 on the contracts v2.71.0
- * (video_compress `audioBitrate` dropped) + v2.73.0 (image Size/Balanced
- * `outputFormat` Smallest/Auto → Original — VcPeRWdD facade self-422 guard) cuts.
+ * The preset matrix version emitted on every resolve. Re-exported from the
+ * GENERATED `sdk_spec/version.ts` (source of truth: contracts
+ * `sdk-spec/version.yaml` `presetVersion`) so it can NEVER drift from the
+ * generated preset cells — a regen that bumps the cells bumps this by
+ * construction. Previously a hand-typed literal that the v2.73.0 regen had to
+ * bump manually (yREs0srv).
  */
-export declare const PRESET_VERSION = "1.2";
+export declare const PRESET_VERSION: "1.4";
 /**
  * Inputs to {@link resolveCompressOptions}. `media` selects which leaf
  * DTO drives sdkDefault + clientDefault lookups + invalid-combo

package/dist/ergonomic/preset_resolver.js

@@ -21,8 +21,8 @@
 //      `quality: 100`, `codec: 'h264'`, …).
 //
 // Validation runs AFTER merge so post-merge-only invariants
-// (targetSize + codec, Lossless + quality) catch combinations where
-// e.g. the explicit knob and a layered default disagree. Resolver
+// (e.g. targetSize + codec on video) catch combinations where
+// the explicit knob and a layered default disagree. Resolver
 // throws `GislConfigError` BEFORE any network round-trip, with a
 // `resolvedSnapshot` showing the would-have-been-sent payload.
 //
@@ -36,33 +36,33 @@
 // to the wire; conversely if `crf` is explicit, `encoding_mode='crf'`.
 import { sha256Hex } from '../sha256.js';
 import { GislConfigError } from '../errors.js';
-import { ImageCompressPresetOptions, AudioCompressPresetOptions, VideoCompressPresetOptions, DocumentPdfCompressPresetOptions, DocumentOfficeCompressPresetOptions, DocumentOdfCompressPresetOptions, DocumentEpubCompressPresetOptions, } from './presets/index.js';
+import { PRESET_VERSION as GENERATED_PRESET_VERSION } from '../generated/sdk_spec/version.js';
+import { ImageCompressPresetOptions, AudioCompressPresetOptions, VideoCompressPresetOptions, DocumentPdfCompressPresetOptions, DocumentOfficeCompressPresetOptions, DocumentOdfCompressPresetOptions, DocumentEpubCompressPresetOptions, definedFieldsOf, } from './presets/index.js';
 /**
- * Bumped on any change to a `*PresetOptions.shippedDefaultsFor(...)` cell value.
- * Must track the contracts `sdk-spec/version.yaml` `presetVersion` (mirrored in
- * the generated `sdk_spec/version.ts`). 1.0 → 1.2 on the contracts v2.71.0
- * (video_compress `audioBitrate` dropped) + v2.73.0 (image Size/Balanced
- * `outputFormat` Smallest/Auto → Original — VcPeRWdD facade self-422 guard) cuts.
+ * The preset matrix version emitted on every resolve. Re-exported from the
+ * GENERATED `sdk_spec/version.ts` (source of truth: contracts
+ * `sdk-spec/version.yaml` `presetVersion`) so it can NEVER drift from the
+ * generated preset cells — a regen that bumps the cells bumps this by
+ * construction. Previously a hand-typed literal that the v2.73.0 regen had to
+ * bump manually (yREs0srv).
  */
-export const PRESET_VERSION = '1.2';
+export const PRESET_VERSION = GENERATED_PRESET_VERSION;
 // ---------------------------------------------------------------------------
 // Wire-field alias map (declarative — NOT generic toSnakeCase).
 // ---------------------------------------------------------------------------
 //
 // Lifted from docs/plans/sdk-ergonomics/plan.md §11a. Maps camelCase
 // ergonomic-DTO field names to their snake_case wire counterparts.
-// Fields whose ergonomic name IS the wire name (`mode`, `quality`,
-// `codec`, …) are NOT in this map — `applyAlias` returns them
-// unchanged. A generic snake-case regex would mistranslate names like
-// `iccProfile` to `i_c_c_profile`; the declarative map is the only
-// safe path.
+// Fields whose ergonomic name IS the wire name (`quality`, `codec`,
+// …) are NOT in this map — `applyAlias` returns them unchanged. A
+// generic snake-case regex would mistranslate acronym/camel names
+// (e.g. an `outputFormat` → `output_format` rename or an acronym like
+// the former `iccProfile`); the declarative map is the only safe path.
 const WIRE_ALIASES = Object.freeze({
-    iccProfile: 'icc_profile',
     outputFormat: 'output_format',
     sampleRate: 'sample_rate',
     audioCodec: 'audio_codec',
     audioBitrate: 'audio_bitrate',
-    flattenForms: 'flatten_forms',
     imageQuality: 'image_quality',
     stripMacros: 'strip_macros',
     stripHiddenData: 'strip_hidden_data',
@@ -199,10 +199,10 @@ function presetDefaultsCellRecord(defaults, media, op, optimize) {
     if (op !== 'compress')
         return undefined;
     // Each overload returns `<Specific>PresetOptions | undefined`. We
-    // erase the per-media type at runtime by spreading the instance
-    // into a plain Record. `cellFor` returns `undefined` when no delta
-    // was registered for the tuple — the resolver treats that the same
-    // as "this layer did not participate."
+    // erase the per-media type at runtime by reducing the instance to a
+    // plain Record. `cellFor` returns `undefined` when no delta was
+    // registered for the tuple — the resolver treats that the same as
+    // "this layer did not participate."
     let cell;
     switch (media) {
         case 'image':
@@ -229,7 +229,16 @@ function presetDefaultsCellRecord(defaults, media, op, optimize) {
     }
     if (cell === undefined)
         return undefined;
-    return { ...cell };
+    // Reduce to a SPARSE camelCase record, dropping undefined-valued keys.
+    // The leaf DTO's field DECLARATIONS define every field as an
+    // own-enumerable `undefined` property under `useDefineForClassFields`
+    // (ES2022) even when the ctor skipped the assignment — a naive spread
+    // would carry those `undefined`s into the presetConfigHash input,
+    // diverging from PHP's sparse `leafToRecord` (SVQcoR1K). `mergeLayer`
+    // already ignores `undefined`, so this only affects the hash path.
+    // Reuses the same helper `PresetDefaults.merge` uses for this exact
+    // `useDefineForClassFields` problem.
+    return definedFieldsOf(cell);
 }
 // ---------------------------------------------------------------------------
 // presetOverrides type-mismatch detection
@@ -241,10 +250,10 @@ function presetDefaultsCellRecord(defaults, media, op, optimize) {
 // for clearly-typed plain objects whose key set only intersects with a
 // non-matching media.
 const MEDIA_FIELDS = Object.freeze({
-    image: new Set(['mode', 'quality', 'metadata', 'iccProfile', 'progressive', 'outputFormat']),
+    image: new Set(['quality', 'metadata', 'outputFormat']),
     audio: new Set(['bitrate', 'channels', 'sampleRate', 'normalize']),
     video: new Set(['codec', 'targetSize', 'crf', 'preset', 'width', 'height', 'fit', 'fps', 'faststart', 'audioCodec', 'audioBitrate']),
-    document_pdf: new Set(['profile', 'colorspace', 'flattenForms']),
+    document_pdf: new Set(['profile', 'grayscale']),
     document_office: new Set(['imageQuality', 'stripMacros', 'stripHiddenData', 'stripUnusedFonts']),
     document_odf: new Set(['imageQuality', 'stripMetadata', 'stripUnusedStyles']),
     document_epub: new Set(['imageQuality', 'fontSubsetting', 'stripUnusedCss']),
@@ -310,10 +319,10 @@ function mergeLayer(acc, layer, source) {
 // can pin this hand-maintained allowlist to the generated contract metadata: every
 // field the resolver may emit MUST be a real contract option key for `compress`.
 export const KNOWN_WIRE_FIELDS = Object.freeze({
-    image: new Set(['mode', 'quality', 'metadata', 'icc_profile', 'progressive', 'output_format']),
+    image: new Set(['quality', 'metadata', 'output_format']),
     audio: new Set(['bitrate', 'channels', 'sample_rate', 'normalize', 'trim_start', 'trim_end']),
     video: new Set(['codec', 'encoding_mode', 'crf', 'target_size_bytes', 'preset', 'width', 'height', 'fit', 'fps', 'faststart', 'audio_codec', 'audio_bitrate', 'trim_start', 'trim_end']),
-    document_pdf: new Set(['profile', 'colorspace', 'pages', 'flatten_forms']),
+    document_pdf: new Set(['profile', 'grayscale']),
     document_office: new Set(['image_quality', 'strip_macros', 'strip_hidden_data', 'strip_unused_fonts']),
     document_odf: new Set(['image_quality', 'strip_metadata', 'strip_unused_styles']),
     document_epub: new Set(['image_quality', 'font_subsetting', 'strip_unused_css']),
@@ -335,19 +344,6 @@ function validateMerged(media, merged, explicitKeys, winners) {
             });
         }
     }
-    // Image: `mode: Lossless` + `quality` set is invalid per the wire
-    // contract (`depends_on: { mode: lossy }`). Runs on post-merge so a
-    // caller passing explicit `quality` and inheriting `mode=Lossless`
-    // from a client preset is caught.
-    if (media === 'image' && merged.mode === 'lossless' && merged.quality !== undefined) {
-        const snapshot = { ...merged };
-        throw new GislConfigError(`Image compress: 'quality' is ignored when 'mode' is Lossless — passing both is a configuration bug.`, {
-            reason: 'missing_dependency',
-            conflictingFields: ['quality', 'mode'],
-            resolvedSnapshot: Object.freeze(snapshot),
-            suggestion: "Either drop 'quality' for lossless output, or set 'mode' to Lossy.",
-        });
-    }
     // Video: targetSize-derived encoding_mode='target_size' is only
     // valid for H264 today. Catch the combination post-merge — explicit
     // codec overrides a layered default and either resolution must end
@@ -406,7 +402,15 @@ function canonicalJson(value) {
         return '[' + value.map(canonicalJson).join(',') + ']';
     }
     const record = value;
-    const keys = Object.keys(record).sort();
+    // Skip undefined-valued keys (mirror `JSON.stringify` object semantics,
+    // which omit undefined members). Without this, `canonicalJson(undefined)`
+    // would serialise the literal token `undefined` into the hash input — a
+    // latent foot-gun. The registered-cell records are already sparse (see
+    // `presetDefaultsCellRecord`), so this is defense-in-depth; the
+    // override-path anchors carry no undefined and are unaffected (SVQcoR1K).
+    const keys = Object.keys(record)
+        .filter((k) => record[k] !== undefined)
+        .sort();
     return ('{' +
         keys
             .map((k) => JSON.stringify(k) + ':' + canonicalJson(record[k]))

package/dist/ergonomic/presets/document_pdf_compress.d.ts

@@ -1,13 +1,11 @@
-import { PdfProfile, PdfColorspace, OptimizeFor } from '../../generated/sdk_spec/enums.js';
+import { PdfProfile, OptimizeFor } from '../../generated/sdk_spec/enums.js';
 export interface DocumentPdfCompressPresetOptionsInput {
     readonly profile?: PdfProfile;
-    readonly colorspace?: PdfColorspace;
-    readonly flattenForms?: boolean;
+    readonly grayscale?: boolean;
 }
 export declare class DocumentPdfCompressPresetOptions {
     readonly profile?: PdfProfile;
-    readonly colorspace?: PdfColorspace;
-    readonly flattenForms?: boolean;
+    readonly grayscale?: boolean;
     private constructor();
     static from(input: DocumentPdfCompressPresetOptionsInput): DocumentPdfCompressPresetOptions;
     static shippedDefaultsFor(level: OptimizeFor): DocumentPdfCompressPresetOptions;

package/dist/ergonomic/presets/document_pdf_compress.js

@@ -1,20 +1,20 @@
 // T4a — DocumentPdfCompressPresetOptions leaf DTO.
 //
-// Field set per ticket VhIj4S7T: PDF = 3 fields (profile, colorspace, flattenForms).
-// Deliberately excluded: `pages` (per-call content selection).
+// Field set (2): profile, grayscale — the worker-honored stable PDF controls
+// (contracts v2.96.0 Acrobat-PDF realignment Lw1LseYr). The earlier
+// {profile, colorspace, flattenForms} set was retired: colorspace + flatten_forms
+// are `planned` (not read by the worker) so presets never emit them, and
+// `image_dpi` + `pages` are per-call knobs, not preset cells.
 import { shippedDefaultsFor as f3ShippedDefaultsFor } from '../../generated/sdk_spec/presets.js';
 import { translateEnum } from './_translate.js';
 export class DocumentPdfCompressPresetOptions {
     profile;
-    colorspace;
-    flattenForms;
+    grayscale;
     constructor(input) {
         if (input.profile !== undefined)
             this.profile = input.profile;
-        if (input.colorspace !== undefined)
-            this.colorspace = input.colorspace;
-        if (input.flattenForms !== undefined)
-            this.flattenForms = input.flattenForms;
+        if (input.grayscale !== undefined)
+            this.grayscale = input.grayscale;
         Object.freeze(this);
     }
     static from(input) {
@@ -26,10 +26,8 @@ export class DocumentPdfCompressPresetOptions {
         const mut = input;
         if ('profile' in cell)
             mut.profile = translateEnum('PdfProfile', cell.profile);
-        if ('colorspace' in cell)
-            mut.colorspace = translateEnum('PdfColorspace', cell.colorspace);
-        if ('flattenForms' in cell)
-            mut.flattenForms = cell.flattenForms;
+        if ('grayscale' in cell)
+            mut.grayscale = cell.grayscale;
         return new DocumentPdfCompressPresetOptions(input);
     }
 }

package/dist/ergonomic/presets/image_compress.d.ts

@@ -1,18 +1,12 @@
-import { ImageMode, ImageMetadataPolicy, IccProfilePolicy, ImageFormat, OptimizeFor } from '../../generated/sdk_spec/enums.js';
+import { ImageMetadataPolicy, ImageFormat, OptimizeFor } from '../../generated/sdk_spec/enums.js';
 export interface ImageCompressPresetOptionsInput {
-    readonly mode?: ImageMode;
     readonly quality?: number;
     readonly metadata?: ImageMetadataPolicy;
-    readonly iccProfile?: IccProfilePolicy;
-    readonly progressive?: boolean;
     readonly outputFormat?: ImageFormat;
 }
 export declare class ImageCompressPresetOptions {
-    readonly mode?: ImageMode;
     readonly quality?: number;
     readonly metadata?: ImageMetadataPolicy;
-    readonly iccProfile?: IccProfilePolicy;
-    readonly progressive?: boolean;
     readonly outputFormat?: ImageFormat;
     private constructor();
     /**
@@ -26,10 +20,9 @@ export declare class ImageCompressPresetOptions {
      * the given level. Reads the F3 PRESETS matrix and translates member
      * names to wire backing values.
      *
-     * Note for OptimizeFor.Quality: the F3 PRESETS cell deliberately
-     * omits `quality` because the contract has `depends_on: { mode: lossy }`
-     * on the quality field — under `mode: Lossless` the API ignores
-     * `quality`, so shipping a default would mislead callers.
+     * Since the v2.80.0 honesty pass the worker is lossy-only, so every
+     * level ships a concrete `quality` (Size 65 / Balanced 80 / Quality 92),
+     * `metadata: All`, and `outputFormat: Original`.
      */
     static shippedDefaultsFor(level: OptimizeFor): ImageCompressPresetOptions;
 }

package/dist/ergonomic/presets/image_compress.js

@@ -7,32 +7,26 @@
 // values ARE the wire backing values — so the leaf DTO is wire-compatible
 // once the resolver (T4b) snake_cases the property names.
 //
-// Field set (6) per EsD1hs5u / contracts v2.60.0: image =
-//   (mode, quality, metadata, iccProfile, progressive, outputFormat).
-// `width`/`height`/`fit`/`autoOrient` were REMOVED — the image-compress
-// worker never resized (resize-fit lives on thumbnail/convert; video keeps
-// its own fit). Trim / per-call knobs are deliberately excluded — they
-// belong on the per-call argument shape, not the preset cell.
+// Field set (3) per contracts v2.80.0 compress.image honesty pass (Option B,
+//   lossy-only): image = (quality, metadata, outputFormat).
+// `mode` + `iccProfile` were REMOVED — the worker is lossy-only and always
+// strips metadata, so advertising a lossless mode or ICC-profile policy was
+// an over-claim. `progressive` is still a per-JPEG wire option but is no
+// longer carried in the preset cell. `width`/`height`/`fit`/`autoOrient`
+// were removed earlier — the image-compress worker never resized (resize-fit
+// lives on thumbnail/convert; video keeps its own fit). Per-call knobs are
+// deliberately excluded — they belong on the per-call argument shape.
 import { shippedDefaultsFor as f3ShippedDefaultsFor } from '../../generated/sdk_spec/presets.js';
 import { translateEnum } from './_translate.js';
 export class ImageCompressPresetOptions {
-    mode;
     quality;
     metadata;
-    iccProfile;
-    progressive;
     outputFormat;
     constructor(input) {
-        if (input.mode !== undefined)
-            this.mode = input.mode;
         if (input.quality !== undefined)
             this.quality = input.quality;
         if (input.metadata !== undefined)
             this.metadata = input.metadata;
-        if (input.iccProfile !== undefined)
-            this.iccProfile = input.iccProfile;
-        if (input.progressive !== undefined)
-            this.progressive = input.progressive;
         if (input.outputFormat !== undefined)
             this.outputFormat = input.outputFormat;
         Object.freeze(this);
@@ -50,25 +44,18 @@ export class ImageCompressPresetOptions {
      * the given level. Reads the F3 PRESETS matrix and translates member
      * names to wire backing values.
      *
-     * Note for OptimizeFor.Quality: the F3 PRESETS cell deliberately
-     * omits `quality` because the contract has `depends_on: { mode: lossy }`
-     * on the quality field — under `mode: Lossless` the API ignores
-     * `quality`, so shipping a default would mislead callers.
+     * Since the v2.80.0 honesty pass the worker is lossy-only, so every
+     * level ships a concrete `quality` (Size 65 / Balanced 80 / Quality 92),
+     * `metadata: All`, and `outputFormat: Original`.
      */
     static shippedDefaultsFor(level) {
         const cell = f3ShippedDefaultsFor('image_compress', level);
         const input = {};
         const mut = input;
-        if ('mode' in cell)
-            mut.mode = translateEnum('ImageMode', cell.mode);
         if ('quality' in cell)
             mut.quality = cell.quality;
         if ('metadata' in cell)
             mut.metadata = translateEnum('ImageMetadataPolicy', cell.metadata);
-        if ('iccProfile' in cell)
-            mut.iccProfile = translateEnum('IccProfilePolicy', cell.iccProfile);
-        if ('progressive' in cell)
-            mut.progressive = cell.progressive;
         if ('outputFormat' in cell)
             mut.outputFormat = translateEnum('ImageFormat', cell.outputFormat);
         return new ImageCompressPresetOptions(input);

package/dist/ergonomic/presets/index.d.ts

@@ -13,7 +13,7 @@ export { DocumentPdfCompressPresetOptions, type DocumentPdfCompressPresetOptions
 export { DocumentOfficeCompressPresetOptions, type DocumentOfficeCompressPresetOptionsInput, } from './document_office_compress.js';
 export { DocumentOdfCompressPresetOptions, type DocumentOdfCompressPresetOptionsInput, } from './document_odf_compress.js';
 export { DocumentEpubCompressPresetOptions, type DocumentEpubCompressPresetOptionsInput, } from './document_epub_compress.js';
-export { OptimizeFor, ImageMode, ImageMetadataPolicy, IccProfilePolicy, ImageFormat, VideoCodec, VideoPreset, VideoFit, AudioBitrate, AudioCodec, AudioSampleRate, PdfProfile, PdfColorspace, } from '../../generated/sdk_spec/enums.js';
+export { OptimizeFor, ImageMetadataPolicy, ImageFormat, VideoCodec, VideoPreset, VideoFit, AudioBitrate, AudioCodec, AudioSampleRate, PdfProfile, PdfColorspace, } from '../../generated/sdk_spec/enums.js';
 /** Supported media×op pairs for preset cells in T4a. Compress-only. */
 export type PresetMedia = 'image' | 'audio' | 'video' | 'document_pdf' | 'document_office' | 'document_odf' | 'document_epub';
 export type PresetOp = 'compress';
@@ -23,6 +23,26 @@ export type PresetOp = 'compress';
  * narrows the return automatically via the overload set below.
  */
 export type AnyPresetOptions = ImageCompressPresetOptions | AudioCompressPresetOptions | VideoCompressPresetOptions | DocumentPdfCompressPresetOptions | DocumentOfficeCompressPresetOptions | DocumentOdfCompressPresetOptions | DocumentEpubCompressPresetOptions;
+/**
+ * Per-cell field-merge: parent fields ⊕ child fields where defined.
+ * Re-construct the leaf DTO via the matching `<LeafClass>.from(merged)`
+ * call so the result is a freshly-frozen `*PresetOptions` instance —
+ * NOT a mutated reference into either input. Used by
+ * {@link PresetDefaults.merge} when both parent and child registered
+ * the same `(cellKey, level)` tuple.
+ *
+ * `definedFieldsOf` filters undefined values out of each instance
+ * BEFORE the merge: with TS `useDefineForClassFields` (the ES2022
+ * default), `readonly outputFormat?: ImageFormat` declarations initialise
+ * the field as an enumerable own property with value `undefined` BEFORE
+ * the ctor body runs. A naive `Object.assign({}, parent, child)`
+ * therefore lets child's `undefined` overwrite parent's defined value
+ * — caught by CI on PR #125 first run. Filter-then-spread restores
+ * the documented merge-not-replace semantics.
+ *
+ * @internal
+ */
+export declare function definedFieldsOf<T extends object>(opts: T): Partial<Record<string, unknown>>;
 export declare class PresetDefaults {
     private readonly cells;
     private constructor();