@giveitsmaller/sdk 0.14.0 → 0.16.0

package/dist/file-first.js

@@ -356,6 +356,33 @@ export function isArchiveStatus(finalStatus) {
     }
     return hasArchive;
 }
+/**
+ * True when a terminal status describes a fluent `file(...).watermark(overlay)`
+ * — at least one job ref `watermark` and every OTHER job ref is `src_{i}` (the
+ * ids the {@link WatermarkedRecipe} lowering assigns: `src_0` base, `src_1`
+ * overlay). Lets {@link Handle.wait}/{@link Handle.result} AND
+ * {@link WatermarkedRecipe.run} project ONLY the watermark output — filtering
+ * the `src_*` passthrough plumbing — even after a `client.workflow(id)` reattach.
+ * Mutually exclusive with {@link isFanoutStatus} / {@link isMergeStatus} /
+ * {@link isArchiveStatus}.
+ *
+ * @internal Exported for the file-first `Handle`; not part of the public API.
+ */
+export function isWatermarkStatus(finalStatus) {
+    const jobs = finalStatus.jobs ?? [];
+    if (jobs.length === 0)
+        return false;
+    let hasWatermark = false;
+    for (const job of jobs) {
+        if (job.ref === 'watermark') {
+            hasWatermark = true;
+            continue;
+        }
+        if (!_MERGE_SRC_REF.test(job.ref))
+            return false;
+    }
+    return hasWatermark;
+}
 /** Named constructors for {@link FileInput} — mirror the PHP static factories. */
 export const fileInput = {
     path(path) {
@@ -472,6 +499,27 @@ export class Recipe {
         // Spread options FIRST so the explicit `text` argument is authoritative.
         return this.withStep({ opType: 'text_watermark', options: { ...options, text } });
     }
+    /**
+     * Composite an image OVERLAY onto this file (a multi-input op). `overlay` is a
+     * secondary file-NODE (a {@link Recipe} — e.g. `client.file('logo.png')`),
+     * itself optionally processed first. Routes by THIS file's effective media:
+     * image base → `image_watermark` (stable), video base → `video_watermark`
+     * (beta). Audio/document/animated-GIF/unsupported-subtype/undetectable bases
+     * throw locally BEFORE any upload (the planned-op gate). `options` carries the
+     * wire watermark options (`anchor`, `opacity`, `margin_x`, `margin_y`,
+     * `overlay_width`). Returns a {@link WatermarkedRecipe} (chain post-watermark
+     * `compress`/`convert`/`thumbnail`, then `run`/`submit`). Distinct from
+     * {@link textWatermark} (single-input text overlay).
+     */
+    watermark(overlay, options = {}) {
+        // Eager gate when the base media is KNOWN (unit-testable pre-upload); an
+        // undetectable base is DEFERRED — re-checked pre-upload in run()/submit().
+        const base = _watermarkEffectiveBase(this.input, this.steps);
+        if (base.media !== undefined)
+            _resolveWatermarkWireOp(base);
+        _validateWatermarkOverlay(overlay);
+        return new WatermarkedRecipe(this.input, this.steps, overlay, options, [], this.presetDefaults, this.scopedPresetDefaults, this.client);
+    }
     /**
      * Lower this recipe to a workflow-create payload against a resolved upload
      * id. Single-input chain → ONE job, `source: upload(fileId)`, ordered
@@ -487,7 +535,7 @@ export class Recipe {
      *   fixed id). Not part of the caller-facing fluent surface.
      */
     toWorkflowPayload(fileId, callbackUrl) {
-        const operations = this.steps.map((step) => this.lowerStep(step));
+        const operations = this.steps.map((step, i) => this.lowerStep(step, i));
         // Key order (source, operations) matches the PHP `toWire()` so the
         // JSON-string serialisation is byte-identical across languages.
         const job = { source: uploadSource(fileId), operations };
@@ -509,6 +557,15 @@ export class Recipe {
     get recipeSteps() {
         return this.steps;
     }
+    /**
+     * The primary input this recipe operates on. Read by {@link WatermarkedRecipe}
+     * to lift an overlay Recipe's input (for upload + media inference + src-job
+     * lowering) without making the ctor field public.
+     * @internal
+     */
+    get recipeInput() {
+        return this.input;
+    }
     /**
      * Execute the recipe end-to-end: upload the input (when required), create
      * the workflow, await a terminal state (SSE with poll fallback), then
@@ -684,15 +741,17 @@ export class Recipe {
     withStep(step) {
         return new Recipe(this.input, this.recipeKey, [...this.steps, step], this.presetDefaults, this.scopedPresetDefaults, this.client);
     }
-    lowerStep(step) {
-        const options = step.opType === 'compress' ? this.lowerCompressOptions(step.options) : { ...step.options };
+    lowerStep(step, stepIndex) {
+        const options = step.opType === 'compress'
+            ? this.lowerCompressOptions(step.options, stepIndex)
+            : { ...step.options };
         // Empty options omit the `options` wire key entirely, so TS (undefined →
         // absent) and PHP (null → absent) serialise byte-identically.
         return Object.keys(options).length === 0
             ? { type: step.opType }
             : { type: step.opType, options };
     }
-    lowerCompressOptions(stepOptions) {
+    lowerCompressOptions(stepOptions, uptoIndex) {
         // Mirror the op-first resolver precedence (OperationBuilder._resolve in
         // builder.ts): optimize = preset layer, presetOverrides = callPresetOverride
         // layer, the rest = explicit layer.
@@ -716,7 +775,7 @@ export class Recipe {
                     : typeof presetOverrides;
             throw new GislConfigError(`compress 'presetOverrides' must be a *CompressPresetOptions object; got ${got}.`, { reason: 'invalid_preset_overrides', conflictingFields: ['presetOverrides'] });
         }
-        const media = this.compressMediaHint();
+        const media = this.compressMediaHint(uptoIndex);
         if (media === undefined) {
             // Cannot infer a media class (a Blob without a recognised name, or a
             // bare upload id) → preset resolution is impossible. Fail FAST rather
@@ -739,7 +798,7 @@ export class Recipe {
         }
         const input = { media, op: 'compress', explicitOptions };
         if (media === 'audio') {
-            input.audioLossless = this.compressAudioLossless();
+            input.audioLossless = this.compressAudioLossless(uptoIndex);
         }
         if (this.presetDefaults !== undefined) {
             input.presetDefaults = this.presetDefaults;
@@ -758,16 +817,52 @@ export class Recipe {
         }
         return { ...resolveCompressOptions(input).wireOptions };
     }
-    compressMediaHint() {
-        if (this.input.kind === 'path') {
+    /** Media of the original input (no chain context) — used by the probe gate. */
+    inputMedia() {
+        if (this.input.kind === 'path')
             return _detectCompressMedia(this.input.path);
-        }
-        if (this.input.kind === 'blob') {
+        if (this.input.kind === 'blob')
             return _detectCompressMedia(this.input.blob);
-        }
         return undefined;
     }
-    compressAudioLossless() {
+    /**
+     * The media class a `compress` step at `uptoIndex` actually operates on. With no
+     * chain context (`uptoIndex` undefined) this is the original input's media. With
+     * context, FOLD the preceding `convert` steps: each `convert(output_format)` changes
+     * the media the next step sees (56N4chXY / N8eESzQN — a chain like
+     * `mp3 -> convert(flac) -> compress` must resolve against flac, not mp3). Reuses the
+     * synthetic-filename detection precedent from {@link MergedRecipe} (`merged.<ext>`).
+     */
+    compressMediaHint(uptoIndex) {
+        let media = this.inputMedia();
+        if (uptoIndex === undefined)
+            return media;
+        for (let i = 0; i < uptoIndex; i++) {
+            const step = this.steps[i];
+            if (step.opType === 'convert') {
+                const fmt = step.options.output_format;
+                if (typeof fmt === 'string')
+                    media = _resolveConvertOutputMedia(media, fmt);
+            }
+        }
+        return media;
+    }
+    /**
+     * Whether the media a `compress` step at `uptoIndex` operates on is lossless audio.
+     * Determined by the most recent preceding `convert` target (`flac`/`wav` -> lossless)
+     * when there is one, else by the original input. Lossless is unaffected by the
+     * video/ogg guard (ogg is never lossless either way).
+     */
+    compressAudioLossless(uptoIndex) {
+        if (uptoIndex !== undefined) {
+            for (let i = uptoIndex - 1; i >= 0; i--) {
+                const step = this.steps[i];
+                if (step.opType === 'convert') {
+                    const fmt = step.options.output_format;
+                    return typeof fmt === 'string' ? _detectAudioLossless(`f.${fmt}`) : false;
+                }
+            }
+        }
         if (this.input.kind === 'path')
             return _detectAudioLossless(this.input.path);
         if (this.input.kind === 'blob')
@@ -775,6 +870,252 @@ export class Recipe {
         return false;
     }
 }
+/**
+ * Media of a `convert` step's output, given the media of its source. Reuses the
+ * extension classifier on a synthetic `f.<format>`, with ONE guard: a video source
+ * converted to `ogg` stays video (an OGG *video* container — `ogg` otherwise lands in
+ * the audio extension list, which would mis-resolve a video output to audio). A video
+ * source to `gif` is left as the classifier's `image` result (animated-GIF compress is
+ * image-class). Per the 56N4chXY plan review (architect + karen).
+ */
+function _resolveConvertOutputMedia(source, outputFormat) {
+    if (source === 'video' && outputFormat.toLowerCase() === 'ogg')
+        return 'video';
+    return _detectCompressMedia(`f.${outputFormat}`);
+}
+// ── Watermark routing + planned-op gating (FF4a) ────────────────────────────
+/**
+ * The single SDK-side source of truth for which `(wire op, base mime)`
+ * combinations the file-first `watermark()` verb may emit, and their
+ * availability. The generated typed metadata sidecar does NOT carry the
+ * supported-mime allowlist (`MimeGroupMetadata` has no `mimes` field and
+ * `per_mime_availability` is empty for these ops), so this hand table is the
+ * gate's source — PINNED to the generated `availability.json` by a conformance
+ * test (mirrors the wire-key-conformance pattern): a contract regen that
+ * changes the supported mimes or availability of `image_watermark` /
+ * `video_watermark` fails that test. The gate reads ONLY this table.
+ * @internal
+ */
+export const WATERMARK_CAPABILITY = {
+    image_watermark: {
+        image: { mimes: ['image/jpeg', 'image/png', 'image/webp'], availability: 'stable' },
+        image_gif: { mimes: ['image/gif'], availability: 'planned' },
+    },
+    video_watermark: {
+        video: { mimes: ['video/mp4', 'video/webm'], availability: 'beta' },
+    },
+};
+const _WATERMARK_SHIPPABLE = new Set(['stable', 'beta']);
+// extension → canonical MIME for the watermark gate. Covers the supported
+// formats PLUS common known-but-unsupported ones so the gate throws an
+// actionable "unsupported subtype" rather than silently routing a format the
+// server will reject.
+const _WATERMARK_EXT_MIME = {
+    jpg: 'image/jpeg', jpeg: 'image/jpeg', png: 'image/png', webp: 'image/webp', gif: 'image/gif',
+    avif: 'image/avif', heic: 'image/heic', heif: 'image/heif', tiff: 'image/tiff', tif: 'image/tiff', bmp: 'image/bmp',
+    mp4: 'video/mp4', webm: 'video/webm', mov: 'video/quicktime', mkv: 'video/x-matroska',
+    avi: 'video/x-msvideo', wmv: 'video/x-ms-wmv', flv: 'video/x-flv', m4v: 'video/x-m4v',
+};
+function _watermarkPathMime(path) {
+    const ext = path.toLowerCase().split('.').pop();
+    return ext !== undefined ? _WATERMARK_EXT_MIME[ext] : undefined;
+}
+/**
+ * The watermark MIME of a base/overlay Blob. Mirrors `_detectCompressMedia`'s
+ * mime-first-else-filename precedence: a declared `Blob.type` is used ONLY when
+ * it is media-bearing (image/ video/ audio/ — params stripped, lowercased); a
+ * generic/unknown type (e.g. `application/octet-stream`) falls back to the
+ * `File.name` extension, so a filename-hinted in-memory base routes like a path.
+ */
+function _watermarkBlobMime(blob) {
+    const raw = blob.type ? blob.type.split(';')[0].trim().toLowerCase() : '';
+    if (raw.startsWith('image/') || raw.startsWith('video/') || raw.startsWith('audio/')) {
+        return raw;
+    }
+    return _watermarkPathMime(blob.name ?? '');
+}
+/**
+ * Resolve the effective `(media, mime)` a watermark op operates on, folding the
+ * preceding `convert` (output media + format) AND `thumbnail` (always an image
+ * output) steps — mirrors {@link Recipe.compressMediaHint}'s convert fold, plus
+ * the thumbnail→image rule (codex review). Reused for the base and the overlay.
+ */
+function _watermarkEffectiveBase(input, steps) {
+    let media = input.kind === 'path'
+        ? _detectCompressMedia(input.path)
+        : input.kind === 'blob'
+            ? _detectCompressMedia(input.blob)
+            : undefined;
+    let mime = input.kind === 'path'
+        ? _watermarkPathMime(input.path)
+        : input.kind === 'blob'
+            ? _watermarkBlobMime(input.blob)
+            : undefined;
+    for (const step of steps) {
+        if (step.opType === 'convert') {
+            const fmt = step.options.output_format;
+            if (typeof fmt === 'string') {
+                media = _resolveConvertOutputMedia(media, fmt);
+                mime = _WATERMARK_EXT_MIME[fmt.toLowerCase()];
+            }
+        }
+        else if (step.opType === 'thumbnail') {
+            // A thumbnail of a video/PDF/image is always an image output.
+            media = 'image';
+            mime = 'image/png';
+        }
+    }
+    // Recover the coarse media from a usable (already-normalised) mime when the
+    // case-sensitive media classifier could not (e.g. an oddly-cased `Image/PNG`
+    // content-type) — keeps the gate self-consistent: a usable mime implies media.
+    if (media === undefined && mime !== undefined) {
+        if (mime.startsWith('image/'))
+            media = 'image';
+        else if (mime.startsWith('video/'))
+            media = 'video';
+        else if (mime.startsWith('audio/'))
+            media = 'audio';
+    }
+    return { media, mime };
+}
+/**
+ * Resolve the wire op (`image_watermark` / `video_watermark`) for a watermark
+ * base, or THROW {@link GislConfigError} pre-upload — the planned-op gate. The
+ * capability is read from {@link WATERMARK_CAPABILITY} (data-driven, contract-
+ * pinned): a base mime in a `{stable,beta}` group routes; a `planned` group
+ * (animated GIF base) throws; a known image/video subtype outside the allowlist
+ * (AVIF/HEIC/MOV/…) throws "unsupported"; audio/document throw "not supported".
+ * An undetectable base media throws an actionable error (the caller defers the
+ * eager check at `.watermark()` time and re-runs this pre-upload).
+ */
+function _resolveWatermarkWireOp(base) {
+    const { media, mime } = base;
+    if (media === undefined) {
+        throw new GislConfigError("watermark needs a detectable base media to route to image_watermark / video_watermark, " +
+            'but the input has no inferable type (a pre-uploaded file id or unnamed/typeless Blob carries ' +
+            'no extension or MIME). Use a path with a file extension, a Blob with a type, or a named resource.', { reason: 'media_unknown' });
+    }
+    if (mime !== undefined) {
+        for (const wireOp of Object.keys(WATERMARK_CAPABILITY)) {
+            const groups = WATERMARK_CAPABILITY[wireOp];
+            for (const group of Object.values(groups)) {
+                if (group.mimes.includes(mime)) {
+                    if (_WATERMARK_SHIPPABLE.has(group.availability))
+                        return wireOp;
+                    throw new GislConfigError(`watermark for ${mime} bases is not yet available (${wireOp} is '${group.availability}'). ` +
+                        'The contract schema is defined but the server returns feature_not_available until it ships.', { reason: 'feature_not_available' });
+                }
+            }
+        }
+    }
+    if (media === 'image' || media === 'video') {
+        throw new GislConfigError(`watermark does not support ${mime ?? media} base files. image_watermark accepts ` +
+            'image/jpeg, image/png, image/webp; video_watermark accepts video/mp4, video/webm. ' +
+            'Convert the base to a supported format first.', { reason: 'unsupported_media' });
+    }
+    throw new GislConfigError(`watermark does not support ${media} base files — overlay watermarking targets image or video bases ` +
+        '(audio overlay and luma matte are planned operations). Use textWatermark() for document/text watermarks.', { reason: 'unsupported_media' });
+}
+/**
+ * Validate a watermark overlay locally: the overlay role is always an IMAGE.
+ * A KNOWN non-image overlay (audio/video/document) throws pre-upload; an
+ * undetectable overlay media is ALLOWED (it doesn't affect routing, so the
+ * server enforces it). The overlay's effective media folds its own steps.
+ */
+function _validateWatermarkOverlay(overlay) {
+    const { media } = _watermarkEffectiveBase(overlay.recipeInput, overlay.recipeSteps);
+    if (media !== undefined && media !== 'image') {
+        throw new GislConfigError(`watermark overlay must be an image; got a ${media} overlay. The overlay is the watermark image ` +
+            'composited onto the base — pass an image file (or a recipe whose output is an image).', { reason: 'invalid_overlay_media', conflictingFields: ['overlay'] });
+    }
+}
+function _lowerWatermarkOp(wireOp, options) {
+    // Watermark options (anchor/opacity/margin_x/margin_y/overlay_width) are
+    // already wire keys; empty options omit the `options` key (byte-identical to PHP).
+    const wire = { ...options };
+    return Object.keys(wire).length === 0 ? { type: wireOp } : { type: wireOp, options: wire };
+}
+/**
+ * Shared multi-input upload-then-create tail for the multi-input recipes
+ * ({@link FilesRecipe}, {@link MergedRecipe}, {@link ArchivedRecipe},
+ * {@link WatermarkedRecipe}). Uploads each fresh input (passing through upload
+ * progress), tracks the multipart-video uploads for the best-effort
+ * probe-before-create, then builds the payload via `toPayload` and creates the
+ * workflow. Abort + deadline are re-checked between every phase, exactly as the
+ * per-recipe copies did before this was extracted (xxy5Rlsy).
+ *
+ * Recipe-specific behaviour stays with the caller: `validatePreUpload()` runs
+ * BEFORE this call (Merged/Archived/Watermarked), and the input source
+ * (`this.inputs` vs `this.inputsInOrder()`) plus the timeout-message nouns
+ * (`uploadsLabel`/`workflowLabel`) are passed in so the thrown messages are
+ * byte-identical to the originals.
+ */
+async function _uploadInputsAndCreate(client, inputs, toPayload, opts) {
+    const { webhook, deadline, onProgress, signal, probeBeforeCreate, probeTimeoutMs, uploadsLabel, workflowLabel } = opts;
+    const fileIds = [];
+    // Track each freshly-uploaded input's probe-gate inputs (a pre-uploaded id
+    // carries no local mime/size, so it is excluded — never probed).
+    const probeTargets = [];
+    for (const input of inputs) {
+        // Fail fast between uploads — a deadline that elapses mid-batch should not
+        // force every remaining input to upload before throwing.
+        _checkAborted(signal);
+        if (deadline !== undefined && Date.now() >= deadline) {
+            throw new GislTimeoutError(`maxWait elapsed during ${uploadsLabel} uploads before all inputs were uploaded`);
+        }
+        if (input.kind === 'uploadId') {
+            fileIds.push(input.fileId);
+        }
+        else {
+            const source = input.kind === 'path' ? input.path : input.blob;
+            const up = await client.uploadFile(source, {
+                signal,
+                ...(onProgress !== undefined
+                    ? {
+                        onProgress: (uploadedBytes, totalBytes) => {
+                            onProgress({ phase: 'upload', uploadedBytes, totalBytes });
+                        },
+                    }
+                    : {}),
+            });
+            fileIds.push(up.fileId);
+            probeTargets.push({
+                fileId: up.fileId,
+                isVideo: _detectCompressMedia(source) === 'video',
+                sizeBytes: up.sizeBytes,
+            });
+        }
+    }
+    _checkAborted(signal);
+    if (deadline !== undefined && Date.now() >= deadline) {
+        throw new GislTimeoutError(`Uploads completed but maxWait elapsed before ${workflowLabel} could be created`);
+    }
+    // Best-effort probe-before-create for the multipart-video inputs. Run the
+    // waits CONCURRENTLY (Promise.all): each is bounded by the SAME capped
+    // timeout, so the aggregate wall-clock stays ~timeout rather than N×timeout.
+    // The cap is the remaining maxWait budget so the waits cannot push
+    // createWorkflow past the caller's deadline. Never-bounce, so a give-up just
+    // proceeds.
+    const cappedProbeTimeoutMs = _cappedProbeTimeoutMs(probeTimeoutMs, deadline);
+    await Promise.all(probeTargets.map((t) => client.maybeWaitForVideoProbe(t.fileId, {
+        enabled: probeBeforeCreate ?? true,
+        isVideo: t.isVideo,
+        sizeBytes: t.sizeBytes,
+        timeoutMs: cappedProbeTimeoutMs,
+        signal,
+    })));
+    // A cancel arriving during a FINAL successful probe request must not still
+    // create the workflow (the probe waits return landed without a final abort
+    // re-check), so check here BEFORE createWorkflow.
+    _checkAborted(signal);
+    // RE-CHECK the deadline AFTER the probe waits (they consume time).
+    if (deadline !== undefined && Date.now() >= deadline) {
+        throw new GislTimeoutError(`Probe wait completed but maxWait elapsed before ${workflowLabel} could be created`);
+    }
+    const created = await client.createWorkflow(toPayload(fileIds, webhook));
+    _checkAborted(signal);
+    return created;
+}
 /**
  * The homogeneous fan-out builder value (FF3a). `client.files([a, b, c])`
  * returns a `FilesRecipe`; the op-chain methods (`compress`, `convert`,
@@ -1000,69 +1341,16 @@ export class FilesRecipe {
      * deadline checks are skipped.
      */
     async _uploadAllAndCreate(webhook, deadline, onProgress, signal, probeBeforeCreate, probeTimeoutMs) {
-        const fileIds = [];
-        // Track each freshly-uploaded input's probe-gate inputs (a pre-uploaded id
-        // carries no local mime/size, so it is excluded — never probed).
-        const probeTargets = [];
-        for (const input of this.inputs) {
-            // Fail fast between uploads — a deadline that elapses mid-batch should
-            // not force every remaining input to upload before throwing.
-            _checkAborted(signal);
-            if (deadline !== undefined && Date.now() >= deadline) {
-                throw new GislTimeoutError('maxWait elapsed during fan-out uploads before all inputs were uploaded');
-            }
-            if (input.kind === 'uploadId') {
-                fileIds.push(input.fileId);
-            }
-            else {
-                const source = input.kind === 'path' ? input.path : input.blob;
-                const up = await this.client.uploadFile(source, {
-                    signal,
-                    ...(onProgress !== undefined
-                        ? {
-                            onProgress: (uploadedBytes, totalBytes) => {
-                                onProgress({ phase: 'upload', uploadedBytes, totalBytes });
-                            },
-                        }
-                        : {}),
-                });
-                fileIds.push(up.fileId);
-                probeTargets.push({
-                    fileId: up.fileId,
-                    isVideo: _detectCompressMedia(source) === 'video',
-                    sizeBytes: up.sizeBytes,
-                });
-            }
-        }
-        _checkAborted(signal);
-        if (deadline !== undefined && Date.now() >= deadline) {
-            throw new GislTimeoutError('Uploads completed but maxWait elapsed before workflow could be created');
-        }
-        // Best-effort probe-before-create for the multipart-video inputs. Run the
-        // waits CONCURRENTLY (Promise.all): each is bounded by the SAME capped
-        // timeout, so the aggregate wall-clock stays ~timeout rather than N×timeout.
-        // The cap is the remaining maxWait budget so the waits cannot push
-        // createWorkflow past the caller's deadline. Never-bounce, so a give-up
-        // just proceeds.
-        const cappedProbeTimeoutMs = _cappedProbeTimeoutMs(probeTimeoutMs, deadline);
-        await Promise.all(probeTargets.map((t) => this.client.maybeWaitForVideoProbe(t.fileId, {
-            enabled: probeBeforeCreate ?? true,
-            isVideo: t.isVideo,
-            sizeBytes: t.sizeBytes,
-            timeoutMs: cappedProbeTimeoutMs,
+        return _uploadInputsAndCreate(this.client, this.inputs, (fileIds, callbackUrl) => this.toWorkflowPayload(fileIds, callbackUrl), {
+            webhook,
+            deadline,
+            onProgress,
             signal,
-        })));
-        // A cancel arriving during a FINAL successful probe request must not still
-        // create the workflow (the probe waits return landed without a final abort
-        // re-check), so check here BEFORE createWorkflow.
-        _checkAborted(signal);
-        // RE-CHECK the deadline AFTER the probe waits (they consume time).
-        if (deadline !== undefined && Date.now() >= deadline) {
-            throw new GislTimeoutError('Probe wait completed but maxWait elapsed before workflow could be created');
-        }
-        const created = await this.client.createWorkflow(this.toWorkflowPayload(fileIds, webhook));
-        _checkAborted(signal);
-        return created;
+            probeBeforeCreate,
+            probeTimeoutMs,
+            uploadsLabel: 'fan-out',
+            workflowLabel: 'workflow',
+        });
     }
     /**
      * The shared single-file {@link Recipe} that captures the op chain (input is
@@ -1259,65 +1547,16 @@ export class MergedRecipe {
      */
     async _uploadAllAndCreate(webhook, deadline, onProgress, signal, probeBeforeCreate, probeTimeoutMs) {
         this.validatePreUpload();
-        const fileIds = [];
-        // Per-input video detection: merge's inferMediaKind decides the OUTPUT
-        // media, not each input's, so detect per input via _detectCompressMedia.
-        // A pre-uploaded id carries no local mime/size, so it is never probed.
-        const probeTargets = [];
-        for (const input of this.inputs) {
-            _checkAborted(signal);
-            if (deadline !== undefined && Date.now() >= deadline) {
-                throw new GislTimeoutError('maxWait elapsed during merge uploads before all inputs were uploaded');
-            }
-            if (input.kind === 'uploadId') {
-                fileIds.push(input.fileId);
-            }
-            else {
-                const source = input.kind === 'path' ? input.path : input.blob;
-                const up = await this.client.uploadFile(source, {
-                    signal,
-                    ...(onProgress !== undefined
-                        ? {
-                            onProgress: (uploadedBytes, totalBytes) => {
-                                onProgress({ phase: 'upload', uploadedBytes, totalBytes });
-                            },
-                        }
-                        : {}),
-                });
-                fileIds.push(up.fileId);
-                probeTargets.push({
-                    fileId: up.fileId,
-                    isVideo: _detectCompressMedia(source) === 'video',
-                    sizeBytes: up.sizeBytes,
-                });
-            }
-        }
-        _checkAborted(signal);
-        if (deadline !== undefined && Date.now() >= deadline) {
-            throw new GislTimeoutError('Uploads completed but maxWait elapsed before the merge workflow could be created');
-        }
-        // Best-effort, concurrent probe-before-create for the multipart-video
-        // inputs (never-bounce; each capped to the remaining maxWait budget so the
-        // waits cannot push createWorkflow past the caller's deadline).
-        const cappedProbeTimeoutMs = _cappedProbeTimeoutMs(probeTimeoutMs, deadline);
-        await Promise.all(probeTargets.map((t) => this.client.maybeWaitForVideoProbe(t.fileId, {
-            enabled: probeBeforeCreate ?? true,
-            isVideo: t.isVideo,
-            sizeBytes: t.sizeBytes,
-            timeoutMs: cappedProbeTimeoutMs,
+        return _uploadInputsAndCreate(this.client, this.inputs, (fileIds, callbackUrl) => this.toWorkflowPayload(fileIds, callbackUrl), {
+            webhook,
+            deadline,
+            onProgress,
             signal,
-        })));
-        // A cancel arriving during a FINAL successful probe request must not still
-        // create the workflow (the probe waits return landed without a final abort
-        // re-check), so check here BEFORE createWorkflow.
-        _checkAborted(signal);
-        // RE-CHECK the deadline AFTER the probe waits (they consume time).
-        if (deadline !== undefined && Date.now() >= deadline) {
-            throw new GislTimeoutError('Probe wait completed but maxWait elapsed before the merge workflow could be created');
-        }
-        const created = await this.client.createWorkflow(this.toWorkflowPayload(fileIds, webhook));
-        _checkAborted(signal);
-        return created;
+            probeBeforeCreate,
+            probeTimeoutMs,
+            uploadsLabel: 'merge',
+            workflowLabel: 'the merge workflow',
+        });
     }
     /**
      * Reject an invalid combine BEFORE any upload fires — mirrors the operation-
@@ -1524,65 +1763,16 @@ export class ArchivedRecipe {
     // ---------------------------------------------------------------------------
     async _uploadAllAndCreate(webhook, deadline, onProgress, signal, probeBeforeCreate, probeTimeoutMs) {
         this.validatePreUpload();
-        const fileIds = [];
-        // Archive is media-agnostic (no inference) — detect per input via
-        // _detectCompressMedia so only video uploads are probed. A pre-uploaded id
-        // carries no local mime/size, so it is never probed.
-        const probeTargets = [];
-        for (const input of this.inputs) {
-            _checkAborted(signal);
-            if (deadline !== undefined && Date.now() >= deadline) {
-                throw new GislTimeoutError('maxWait elapsed during archive uploads before all inputs were uploaded');
-            }
-            if (input.kind === 'uploadId') {
-                fileIds.push(input.fileId);
-            }
-            else {
-                const source = input.kind === 'path' ? input.path : input.blob;
-                const up = await this.client.uploadFile(source, {
-                    signal,
-                    ...(onProgress !== undefined
-                        ? {
-                            onProgress: (uploadedBytes, totalBytes) => {
-                                onProgress({ phase: 'upload', uploadedBytes, totalBytes });
-                            },
-                        }
-                        : {}),
-                });
-                fileIds.push(up.fileId);
-                probeTargets.push({
-                    fileId: up.fileId,
-                    isVideo: _detectCompressMedia(source) === 'video',
-                    sizeBytes: up.sizeBytes,
-                });
-            }
-        }
-        _checkAborted(signal);
-        if (deadline !== undefined && Date.now() >= deadline) {
-            throw new GislTimeoutError('Uploads completed but maxWait elapsed before the archive workflow could be created');
-        }
-        // Best-effort, concurrent probe-before-create for the multipart-video
-        // inputs (never-bounce; each capped to the remaining maxWait budget so the
-        // waits cannot push createWorkflow past the caller's deadline).
-        const cappedProbeTimeoutMs = _cappedProbeTimeoutMs(probeTimeoutMs, deadline);
-        await Promise.all(probeTargets.map((t) => this.client.maybeWaitForVideoProbe(t.fileId, {
-            enabled: probeBeforeCreate ?? true,
-            isVideo: t.isVideo,
-            sizeBytes: t.sizeBytes,
-            timeoutMs: cappedProbeTimeoutMs,
+        return _uploadInputsAndCreate(this.client, this.inputs, (fileIds, callbackUrl) => this.toWorkflowPayload(fileIds, callbackUrl), {
+            webhook,
+            deadline,
+            onProgress,
             signal,
-        })));
-        // A cancel arriving during a FINAL successful probe request must not still
-        // create the workflow (the probe waits return landed without a final abort
-        // re-check), so check here BEFORE createWorkflow.
-        _checkAborted(signal);
-        // RE-CHECK the deadline AFTER the probe waits (they consume time).
-        if (deadline !== undefined && Date.now() >= deadline) {
-            throw new GislTimeoutError('Probe wait completed but maxWait elapsed before the archive workflow could be created');
-        }
-        const created = await this.client.createWorkflow(this.toWorkflowPayload(fileIds, webhook));
-        _checkAborted(signal);
-        return created;
+            probeBeforeCreate,
+            probeTimeoutMs,
+            uploadsLabel: 'archive',
+            workflowLabel: 'the archive workflow',
+        });
     }
     /**
      * Reject an invalid bundle BEFORE any upload fires — the archive schema allows
@@ -1610,3 +1800,213 @@ export class ArchivedRecipe {
         return out;
     }
 }
+/**
+ * The single-output recipe you're in AFTER `file(base).watermark(overlay, …)`
+ * (FF4a). Composites an image OVERLAY onto the base (image_watermark for image
+ * bases, video_watermark for video bases — routed at lowering by the base's
+ * effective media). A multi-input op: base + overlay each enter via their own
+ * `passthrough` source job (`src_0` base, `src_1` overlay; their own preceding
+ * steps lower into those jobs), and the `watermark` job consumes them via
+ * `job_output` inputs tagged `role: base` / `role: overlay`. Post-watermark
+ * `compress`/`convert`/`thumbnail` chain onto the watermark output. Mirrors
+ * {@link MergedRecipe}. `textWatermark` is intentionally NOT a post-verb here.
+ */
+export class WatermarkedRecipe {
+    baseInput;
+    baseSteps;
+    overlay;
+    watermarkOptions;
+    postSteps;
+    presetDefaults;
+    scopedPresetDefaults;
+    client;
+    constructor(baseInput, baseSteps, overlay, watermarkOptions, postSteps = [], presetDefaults, scopedPresetDefaults, client) {
+        this.baseInput = baseInput;
+        this.baseSteps = baseSteps;
+        this.overlay = overlay;
+        this.watermarkOptions = watermarkOptions;
+        this.postSteps = postSteps;
+        this.presetDefaults = presetDefaults;
+        this.scopedPresetDefaults = scopedPresetDefaults;
+        this.client = client;
+    }
+    /** Reduce the watermarked output's size. See {@link Recipe.compress}. */
+    compress(optimize, options = {}) {
+        if (optimize !== undefined && !Object.values(OptimizeFor).includes(optimize)) {
+            const allowed = Object.values(OptimizeFor).join(', ');
+            throw new GislConfigError(`compress 'optimize' must be one of ${allowed}; got '${String(optimize)}'.`, { reason: 'invalid_optimize', conflictingFields: ['optimize'] });
+        }
+        return this.withStep({
+            opType: 'compress',
+            options: { ...options, ...(optimize !== undefined ? { optimize } : {}) },
+        });
+    }
+    /** Change the watermarked output's format. See {@link Recipe.convert}. */
+    convert(format, options = {}) {
+        const rest = { ...options };
+        delete rest.format;
+        return this.withStep({ opType: 'convert', options: { ...rest, output_format: format } });
+    }
+    /** Thumbnail the watermarked output. Omitted dimensions are dropped from the wire options. */
+    thumbnail(options = {}) {
+        const wire = {};
+        for (const [key, value] of Object.entries(options)) {
+            if (value !== undefined)
+                wire[key] = value;
+        }
+        return this.withStep({ opType: 'thumbnail', options: wire });
+    }
+    /**
+     * Lower to the watermark DAG: a `src_0` passthrough/base-steps job + a `src_1`
+     * passthrough/overlay-steps job + one `watermark` job whose `inputs[]` consume
+     * them via `job_output` (role base/overlay) and whose `operations[]` is
+     * `[image_watermark|video_watermark, ...post-watermark ops]`. `fileIds` is
+     * `[baseId, overlayId]` (upload order). Throws pre-lowering if the base media
+     * is undetectable/unsupported (the planned-op gate).
+     *
+     * @internal Consumed by {@link run}/{@link submit} (after upload) + the parity harness.
+     */
+    toWorkflowPayload(fileIds, callbackUrl) {
+        const wireOp = _resolveWatermarkWireOp(_watermarkEffectiveBase(this.baseInput, this.baseSteps));
+        const baseId = fileIds[0];
+        const overlayId = fileIds[1];
+        // src_0: the base (its preceding steps, else a lossless passthrough).
+        const baseOps = this.baseSteps.length > 0
+            ? new Recipe(this.baseInput, undefined, this.baseSteps, this.presetDefaults, this.scopedPresetDefaults)
+                .toWorkflowPayload(baseId).jobs[0].operations
+            : [{ type: 'passthrough' }];
+        // src_1: the overlay recipe (its own steps, else a lossless passthrough).
+        const overlayOps = this.overlay.recipeSteps.length > 0
+            ? this.overlay.toWorkflowPayload(overlayId).jobs[0].operations
+            : [{ type: 'passthrough' }];
+        // Key order (id, source, operations) matches PHP toWire() — byte-identical JSON.
+        const srcBase = { id: 'src_0', source: uploadSource(baseId), operations: baseOps };
+        const srcOverlay = { id: 'src_1', source: uploadSource(overlayId), operations: overlayOps };
+        const inputs = [
+            { source: jobOutputSource('src_0'), role: 'base' },
+            { source: jobOutputSource('src_1'), role: 'overlay' },
+        ];
+        const operations = [
+            _lowerWatermarkOp(wireOp, this.watermarkOptions),
+            ...this.lowerPostSteps(wireOp),
+        ];
+        const watermarkJob = { id: 'watermark', inputs, operations };
+        const jobs = [srcBase, srcOverlay, watermarkJob];
+        return callbackUrl === undefined ? { jobs } : { jobs, callback_url: callbackUrl };
+    }
+    /** The number of post-watermark ops chained so far (introspection / tests). */
+    get stepCount() {
+        return this.postSteps.length;
+    }
+    /**
+     * Execute end-to-end: upload base + overlay, create the watermark workflow,
+     * await terminal (SSE with poll fallback), then resolve ONLY the watermark
+     * output into a {@link RunResult}. Requires a client bound at construction.
+     * Mirrors {@link MergedRecipe.run}.
+     */
+    async run(options = {}) {
+        const signal = options.signal;
+        const onProgress = options.onProgress;
+        if (this.client === undefined) {
+            throw new GislConfigError('WatermarkedRecipe.run() requires a client; build the watermark via gisl().file(...).watermark(...) rather than constructing WatermarkedRecipe directly.', { reason: 'no_client' });
+        }
+        const deadline = Date.now() + _parseMaxWait(options.maxWait ?? 300_000);
+        const created = await this._uploadAllAndCreate(undefined, deadline, onProgress, signal, options.probeBeforeCreate, options.probeTimeoutMs);
+        let finalStatus;
+        try {
+            finalStatus = await _consumeSseToTerminal(this.client, {
+                workflowId: created.workflowId,
+                deadline,
+                signal,
+                onProgress,
+            });
+        }
+        catch (err) {
+            if (!(err instanceof SseEndedWithoutTerminal || err instanceof GislNetworkError)) {
+                throw err;
+            }
+            finalStatus = await _pollToTerminal(this.client, {
+                workflowId: created.workflowId,
+                deadline,
+                signal,
+                pollIntervalMs: options.pollIntervalMs,
+            });
+        }
+        if (Date.now() >= deadline) {
+            throw new GislTimeoutError(`Workflow ${created.workflowId} reached terminal status but maxWait elapsed before downloads could be fetched`);
+        }
+        const downloads = await this.client.getWorkflowDownloads(created.workflowId);
+        if (Date.now() >= deadline) {
+            throw new GislTimeoutError(`Workflow ${created.workflowId} downloads fetch completed after maxWait elapsed`);
+        }
+        // Project ONLY the watermark job's output — the `src_*` passthrough jobs
+        // re-expose the raw base/overlay uploads, which are plumbing.
+        const watermarkDownloads = downloads.downloads.filter((d) => d.ref === 'watermark');
+        const downloader = new LazyHttpDownloader();
+        return projectDownloadsToRunResult(created.workflowId, finalStatus, watermarkDownloads, null, downloader);
+    }
+    /**
+     * Fire-and-forget: upload base + overlay + create the watermark workflow
+     * (wiring `webhook` into `callback_url` when given), return a client-bound
+     * {@link Handle}. Does NOT wait for terminal status. Mirrors {@link MergedRecipe.submit}.
+     */
+    async submit(webhook, options) {
+        if (this.client === undefined) {
+            throw new GislConfigError('WatermarkedRecipe.submit() requires a client; build the watermark via gisl().file(...).watermark(...) rather than constructing WatermarkedRecipe directly.', { reason: 'no_client' });
+        }
+        const created = await this._uploadAllAndCreate(webhook, undefined, undefined, undefined, options?.probeBeforeCreate, options?.probeTimeoutMs);
+        return new Handle(created.workflowId, created.webhookSecret != null ? created.webhookSecret : undefined, this.client, null);
+    }
+    // ---------------------------------------------------------------------------
+    /** Base + overlay inputs, in upload/lowering order (`[base, overlay]`). */
+    inputsInOrder() {
+        return [this.baseInput, this.overlay.recipeInput];
+    }
+    /**
+     * Validate the watermark BEFORE any upload: the base must route to a shippable
+     * wire op (throws for undetectable/unsupported/planned bases), and the overlay
+     * must be an image. Shared by {@link run}/{@link submit}. Mirrors
+     * {@link MergedRecipe.validatePreUpload}.
+     */
+    validatePreUpload() {
+        _resolveWatermarkWireOp(_watermarkEffectiveBase(this.baseInput, this.baseSteps));
+        _validateWatermarkOverlay(this.overlay);
+    }
+    /**
+     * Upload base + overlay (verbatim for a pre-uploaded id; uploading a path /
+     * blob otherwise) then create ONE watermark workflow. Validates pre-upload.
+     * Shared first half of {@link run} + {@link submit}; mirrors
+     * {@link MergedRecipe._uploadAllAndCreate}.
+     */
+    async _uploadAllAndCreate(webhook, deadline, onProgress, signal, probeBeforeCreate, probeTimeoutMs) {
+        this.validatePreUpload();
+        return _uploadInputsAndCreate(this.client, this.inputsInOrder(), (fileIds, callbackUrl) => this.toWorkflowPayload(fileIds, callbackUrl), {
+            webhook,
+            deadline,
+            onProgress,
+            signal,
+            probeBeforeCreate,
+            probeTimeoutMs,
+            uploadsLabel: 'watermark',
+            workflowLabel: 'the watermark workflow',
+        });
+    }
+    /**
+     * Lower the post-watermark chain over a synthetic input whose extension
+     * matches the watermark OUTPUT media (image→png, video→mp4) so
+     * `compress(optimize)` resolves the correct preset — mirrors
+     * {@link MergedRecipe.lowerPostSteps}.
+     */
+    lowerPostSteps(wireOp) {
+        if (this.postSteps.length === 0) {
+            return [];
+        }
+        const ext = wireOp === 'video_watermark' ? 'mp4' : 'png';
+        const synthetic = fileInput.path(`watermarked.${ext}`);
+        const recipe = new Recipe(synthetic, undefined, this.postSteps, this.presetDefaults, this.scopedPresetDefaults);
+        return recipe.toWorkflowPayload('watermarked').jobs[0].operations;
+    }
+    withStep(step) {
+        return new WatermarkedRecipe(this.baseInput, this.baseSteps, this.overlay, this.watermarkOptions, [...this.postSteps, step], this.presetDefaults, this.scopedPresetDefaults, this.client);
+    }
+}