@crabcrop/mcp 0.0.0-stage → 0.9.11

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,722 @@
1
+ /**
2
+ * Typed builders for crabcrop operation strings (AP-24).
3
+ *
4
+ * `buildURL` takes operations verbatim, by design: the string
5
+ * is the spec. This module is the optional typed surface over
6
+ * it: each call validates its arguments against the server's
7
+ * grammar (the same bounds the explainer enforces) and returns
8
+ * the operation segment in its canonical spelling, so a typed
9
+ * pipeline and the equivalent hand-written string produce
10
+ * byte-identical URLs. Validation throws at build time, like
11
+ * `buildSrcSet` does for widths: a value the server would 400
12
+ * never gets signed.
13
+ */
14
+ const PER_FORMAT_QUALITY_FORMATS = [
15
+ "avif",
16
+ "gif",
17
+ "jpeg",
18
+ "jxl",
19
+ "png",
20
+ "webp",
21
+ ];
22
+ const MAX_DIMENSION = 16383;
23
+ function fail(what, value, rule) {
24
+ throw new Error(`${what} must be ${rule}, got ${JSON.stringify(value)}`);
25
+ }
26
+ function intIn(what, value, min, max) {
27
+ if (!Number.isSafeInteger(value) || value < min || value > max) {
28
+ fail(what, value, `an integer from ${min} to ${max}`);
29
+ }
30
+ return value;
31
+ }
32
+ function floatIn(what, value, min, max) {
33
+ if (!Number.isFinite(value) || value < min || value > max) {
34
+ fail(what, value, `a number from ${min} to ${max}`);
35
+ }
36
+ return value;
37
+ }
38
+ function positiveFloat(what, value) {
39
+ if (!Number.isFinite(value) || value <= 0) {
40
+ fail(what, value, "a positive number");
41
+ }
42
+ return value;
43
+ }
44
+ /**
45
+ * The canonical number spelling: integers without a fraction,
46
+ * other values in plain decimal (the grammar takes no
47
+ * exponent forms). JavaScript's shortest round-trip spelling
48
+ * agrees with the server's for the magnitudes the grammar
49
+ * allows; exponent spellings are expanded to plain decimal.
50
+ */
51
+ function num(value) {
52
+ if (Number.isSafeInteger(value))
53
+ return String(value);
54
+ const s = String(value);
55
+ if (!s.includes("e"))
56
+ return s;
57
+ return value
58
+ .toFixed(12)
59
+ .replace(/0+$/, "")
60
+ .replace(/\.$/, "");
61
+ }
62
+ function dimension(what, value) {
63
+ if (value === "orig")
64
+ return "orig";
65
+ if (!Number.isSafeInteger(value) || Math.abs(value) > MAX_DIMENSION) {
66
+ fail(what, value, `a pixel count up to ${MAX_DIMENSION}, 0, or "orig"`);
67
+ }
68
+ return String(value);
69
+ }
70
+ function pixelBox(what, width, height) {
71
+ intIn(`${what} width`, width, 1, MAX_DIMENSION);
72
+ intIn(`${what} height`, height, 1, MAX_DIMENSION);
73
+ return `${width}x${height}`;
74
+ }
75
+ function hex6(what, value) {
76
+ if (!/^[0-9a-fA-F]{6}$/.test(value)) {
77
+ fail(what, value, "six hex digits (RRGGBB)");
78
+ }
79
+ return value.toLowerCase();
80
+ }
81
+ function hex6or8(what, value) {
82
+ if (/^[0-9a-fA-F]{6}$/.test(value))
83
+ return `${value.toLowerCase()}ff`;
84
+ if (/^[0-9a-fA-F]{8}$/.test(value))
85
+ return value.toLowerCase();
86
+ return fail(what, value, "six or eight hex digits (RRGGBB or RRGGBBAA)");
87
+ }
88
+ /**
89
+ * The canonical percent-encoding for filter arguments that
90
+ * carry text (watermark and overlay URLs, class names, text
91
+ * labels): everything outside the RFC 3986 unreserved set is
92
+ * encoded, byte-wise, exactly as the server's canonical form
93
+ * spells it.
94
+ */
95
+ function encodeArg(text) {
96
+ return encodeURIComponent(text).replace(/[!'()*]/g, (c) => `%${c.charCodeAt(0).toString(16).toUpperCase().padStart(2, "0")}`);
97
+ }
98
+ function className(what, name) {
99
+ const trimmed = name.trim();
100
+ // The server's bound is on UTF-8 bytes, not UTF-16 code
101
+ // units: a name of multibyte characters can pass a
102
+ // length check here and still be rejected there, so
103
+ // measure the encoded form, as the explainer does.
104
+ const bytes = new TextEncoder().encode(trimmed).length;
105
+ if (bytes < 1 || bytes > 64 || !/^[\p{L}\p{N} _.\-/]+$/u.test(trimmed)) {
106
+ fail(what, name, "1 to 64 UTF-8 bytes of letters, digits, space, `_`, `.`, `-`, `/`");
107
+ }
108
+ return encodeArg(name);
109
+ }
110
+ const CROP_ALIGNS = ["center", "smart", "face", "top", "bottom", "left", "right", "top-left", "top-right", "bottom-left", "bottom-right"];
111
+ const ANCHORS = [
112
+ "top-left",
113
+ "top-center",
114
+ "top-right",
115
+ "center-left",
116
+ "center",
117
+ "center-right",
118
+ "bottom-left",
119
+ "bottom-center",
120
+ "bottom-right",
121
+ ];
122
+ const BLEND_MODES = ["normal", "multiply", "screen", "overlay"];
123
+ const CURVE_CHANNELS = ["rgb", "r", "g", "b"];
124
+ const STUDIO_MODES = ["product", "scene"];
125
+ const STUDIO_SHADOWS = ["soft", "strong", "none"];
126
+ const IMAGE_FORMATS = ["jpeg", "jpg", "png", "webp", "jxl", "avif", "gif", "mp4", "webm"];
127
+ /** Operation segments, one typed call per segment kind. */
128
+ export const ops = {
129
+ /** `300x200`; each side a Dimension (0 proportional, negative flips). */
130
+ size(width, height) {
131
+ return `${dimension("width", width)}x${dimension("height", height)}`;
132
+ },
133
+ /**
134
+ * `fit-in:300x200`; no flips (the server rejects them here).
135
+ * With `adaptive`, `fit-in:300x200:adaptive`: the box axes
136
+ * swap when the source orientation disagrees with the box's.
137
+ */
138
+ fitIn(width, height, adaptive = false) {
139
+ for (const [what, v] of [
140
+ ["width", width],
141
+ ["height", height],
142
+ ]) {
143
+ if (typeof v === "number" && v < 0) {
144
+ fail(`fit-in ${what}`, v, "not a flip: fit-in takes no negative sizes");
145
+ }
146
+ }
147
+ const base = `fit-in:${dimension("width", width)}x${dimension("height", height)}`;
148
+ return adaptive ? `${base}:adaptive` : base;
149
+ },
150
+ /** `crop:300x200` or `crop:300x200:smart`; an exact pixel box. */
151
+ crop(width, height, align = "center") {
152
+ if (!CROP_ALIGNS.includes(align)) {
153
+ fail("crop align", align, `one of ${CROP_ALIGNS.join(", ")}`);
154
+ }
155
+ const box = pixelBox("crop", width, height);
156
+ return align === "center" ? `crop:${box}` : `crop:${box}:${align}`;
157
+ },
158
+ /**
159
+ * `crop:300x200:objects(person,car):1.5`; crops to the
160
+ * union of every detection of the named classes, the
161
+ * union box scaled about its center by `scale` (1 is the
162
+ * tight box; the crop stays centered on the union).
163
+ * Needs a detection model configured on the server; when
164
+ * none of the classes is detected the render falls back
165
+ * to the plain center crop of the same size. Duplicate
166
+ * classes (case-insensitive) are spelled once, as the
167
+ * server's canonical form spells them; at most 32
168
+ * distinct classes, and a 33rd throws, since the server
169
+ * rejects it with `invalid_crop`.
170
+ */
171
+ cropObjects(width, height, classes, scale = 1) {
172
+ if (!Array.isArray(classes) || classes.length < 1) {
173
+ fail("crop objects classes", classes, "an array of 1 to 32 distinct class names");
174
+ }
175
+ // The cap counts distinct names, as the server's parser
176
+ // does (issue #408): repeats fold first and cost nothing.
177
+ const seen = new Set();
178
+ const names = [];
179
+ for (const name of classes) {
180
+ const encoded = className("crop objects class", name);
181
+ const key = typeof name === "string" ? name.trim().toLowerCase() : "";
182
+ if (!seen.has(key)) {
183
+ if (names.length === 32) {
184
+ fail("crop objects classes", classes, "an array of 1 to 32 distinct class names");
185
+ }
186
+ seen.add(key);
187
+ names.push(encoded);
188
+ }
189
+ }
190
+ if (!Number.isFinite(scale) || scale <= 0 || scale > 100) {
191
+ fail("crop objects scale", scale, "a number above 0 and at most 100");
192
+ }
193
+ const box = pixelBox("crop", width, height);
194
+ return `crop:${box}:objects(${names.join(",")}):${num(scale)}`;
195
+ },
196
+ /** `crop-rect:10x20:110x220` (left x top : right x bottom). */
197
+ cropRect(left, top, right, bottom) {
198
+ intIn("crop-rect left", left, 0, 4294967295);
199
+ intIn("crop-rect top", top, 0, 4294967295);
200
+ intIn("crop-rect right", right, 0, 4294967295);
201
+ intIn("crop-rect bottom", bottom, 0, 4294967295);
202
+ if (right <= left || bottom <= top) {
203
+ fail("crop-rect", `${left}x${top}:${right}x${bottom}`, "right > left and bottom > top");
204
+ }
205
+ return `crop-rect:${left}x${top}:${right}x${bottom}`;
206
+ },
207
+ /** `focal:10x20:110x220` (left x top : right x bottom); steers the next crop. */
208
+ focal(left, top, right, bottom) {
209
+ intIn("focal left", left, 0, 4294967295);
210
+ intIn("focal top", top, 0, 4294967295);
211
+ intIn("focal right", right, 0, 4294967295);
212
+ intIn("focal bottom", bottom, 0, 4294967295);
213
+ if (right <= left || bottom <= top) {
214
+ fail("focal", `${left}x${top}:${right}x${bottom}`, "right > left and bottom > top");
215
+ }
216
+ return `focal:${left}x${top}:${right}x${bottom}`;
217
+ },
218
+ /** `focalpoint:0.75x0.4:2` (fractions of the image dimensions, zoom optional); steers the next crop. */
219
+ focalPoint(x, y, zoom = 1) {
220
+ const frac = (what, v) => {
221
+ if (!Number.isFinite(v) || v < 0 || v > 1) {
222
+ fail(what, v, "a fraction from 0 to 1");
223
+ }
224
+ return v;
225
+ };
226
+ if (!Number.isFinite(zoom) || zoom <= 0 || zoom > 100) {
227
+ fail("focalpoint zoom", zoom, "a number above 0 and at most 100");
228
+ }
229
+ return `focalpoint:${num(frac("focalpoint x", x))}x${num(frac("focalpoint y", y))}:${num(zoom)}`;
230
+ },
231
+ /** `pad:300x200`, optionally `:blur` or a RRGGBB fill color. */
232
+ pad(width, height, fill) {
233
+ const box = pixelBox("pad", width, height);
234
+ if (fill === undefined)
235
+ return `pad:${box}`;
236
+ if (fill === "blur")
237
+ return `pad:${box}:blur`;
238
+ return `pad:${box}:${hex6("pad fill", fill)}`;
239
+ },
240
+ /** `preset:thumb`; expands server-side. */
241
+ preset(name) {
242
+ // The server can only configure names from this
243
+ // charset (its preset file validation), so anything
244
+ // outside it is a reference that can only ever answer
245
+ // unknown_preset; refuse it here instead.
246
+ if (!/^[A-Za-z0-9_-]+$/.test(name)) {
247
+ fail("preset name", name, "letters, digits, `_`, `-` (the server's preset name charset)");
248
+ }
249
+ return `preset:${name}`;
250
+ },
251
+ /**
252
+ * `maxage:60`; this response's Cache-Control lifetime in
253
+ * seconds (0 to 31536000), overriding the default year for
254
+ * this request only. Header-only: it never enters the
255
+ * cache key, so spellings that differ only here share one
256
+ * stored image.
257
+ */
258
+ maxage(seconds) {
259
+ return `maxage:${intIn("maxage seconds", seconds, 0, 31536000)}`;
260
+ },
261
+ /**
262
+ * `debug:focal`; the smart-crop debug view. Place it
263
+ * before the crop it annotates: the response is a
264
+ * diagnostic image of the focal decision (focal point,
265
+ * focal rectangle, crop window drawn on the crop's
266
+ * canvas), never the transform result, and it is never
267
+ * cached (served with Cache-Control: no-store).
268
+ */
269
+ debugFocal() {
270
+ return "debug:focal";
271
+ },
272
+ /** Join filter calls into one `filters:` segment. */
273
+ filters(...calls) {
274
+ if (calls.length === 0) {
275
+ fail("filters", calls, "at least one filter call");
276
+ }
277
+ return `filters:${calls.join(":")}`;
278
+ },
279
+ };
280
+ /** Join operation segments into the operations string `buildURL` takes. */
281
+ export function joinOps(...segments) {
282
+ return segments.join("/");
283
+ }
284
+ /** Filter calls for `ops.filters(...)`; each returns its canonical spelling. */
285
+ export const filter = {
286
+ grayscale() {
287
+ return "grayscale";
288
+ },
289
+ invert() {
290
+ return "invert";
291
+ },
292
+ noUpscale() {
293
+ return "no_upscale";
294
+ },
295
+ equalize() {
296
+ return "equalize";
297
+ },
298
+ enhance() {
299
+ return "enhance";
300
+ },
301
+ removeBg() {
302
+ return "removebg";
303
+ },
304
+ keepProfile() {
305
+ return "keep_profile";
306
+ },
307
+ sepia() {
308
+ return "sepia";
309
+ },
310
+ blurFaces() {
311
+ return "blurfaces";
312
+ },
313
+ pixelateFaces() {
314
+ return "pixelatefaces";
315
+ },
316
+ /** Gaussian blur by sigma: positive, at most the server's 512 cap. */
317
+ blur(sigma) {
318
+ if (!Number.isFinite(sigma) || sigma <= 0 || sigma > 512) {
319
+ fail("blur sigma", sigma, "a positive number up to 512");
320
+ }
321
+ return `blur(${num(sigma)})`;
322
+ },
323
+ /** Unsharp-mask strength (positive). */
324
+ sharpen(amount) {
325
+ return `sharpen(${num(positiveFloat("sharpen amount", amount))})`;
326
+ },
327
+ /** Add to every channel: -255..255. */
328
+ brighten(amount) {
329
+ return `brighten(${intIn("brighten amount", amount, -255, 255)})`;
330
+ },
331
+ /** Percent contrast: -100..100 (0 unchanged, -100 flat). */
332
+ contrast(percent) {
333
+ return `contrast(${num(floatIn("contrast", percent, -100, 100))})`;
334
+ },
335
+ /** Gamma correction divisor: 0 < g <= 10 (1 unchanged; above 1 brightens midtones). */
336
+ gamma(value) {
337
+ if (!Number.isFinite(value) || value <= 0 || value > 10) {
338
+ fail("gamma", value, "a number above 0 and at most 10");
339
+ }
340
+ return `gamma(${num(value)})`;
341
+ },
342
+ /** Exposure in stops: -10..10 (0 unchanged; +1 doubles the light, -1 halves it). */
343
+ exposure(stops) {
344
+ if (!Number.isFinite(stops) || stops < -10 || stops > 10) {
345
+ fail("exposure", stops, "a number between -10 and 10");
346
+ }
347
+ return `exposure(${num(stops)})`;
348
+ },
349
+ /** Highlights and shadows: two percents, each -100..100 (0 unchanged). */
350
+ highlightsShadows(highlights, shadows) {
351
+ return `highlights_shadows(${num(floatIn("highlights_shadows highlights", highlights, -100, 100))},${num(floatIn("highlights_shadows shadows", shadows, -100, 100))})`;
352
+ },
353
+ /** Vibrance percent: -100..100 (0 unchanged; muted colors move most, vivid colors are protected). */
354
+ vibrance(percent) {
355
+ return `vibrance(${num(floatIn("vibrance", percent, -100, 100))})`;
356
+ },
357
+ /** Rotate the hue by integer degrees. */
358
+ hueRotate(degrees) {
359
+ return `huerotate(${intIn("huerotate degrees", degrees, -2147483648, 2147483647)})`;
360
+ },
361
+ /** Saturation factor: 0..255 (0 grayscale, 1 identity). */
362
+ saturation(factor) {
363
+ return `saturation(${num(floatIn("saturation", factor, 0, 255))})`;
364
+ },
365
+ /** Per-channel offsets, each -255..255. */
366
+ rgb(r, g, b) {
367
+ return `rgb(${intIn("rgb red", r, -255, 255)},${intIn("rgb green", g, -255, 255)},${intIn("rgb blue", b, -255, 255)})`;
368
+ },
369
+ /**
370
+ * Tone curve: remap the channel through 2 to 16 [x, y]
371
+ * control points, each coordinate 0..255 with x strictly
372
+ * increasing. Between points the server interpolates
373
+ * linearly; inputs outside the point range clamp to the
374
+ * nearest end value.
375
+ */
376
+ curve(channel, points) {
377
+ if (!CURVE_CHANNELS.includes(channel)) {
378
+ fail("curve channel", channel, `one of ${CURVE_CHANNELS.join(", ")}`);
379
+ }
380
+ if (points.length < 2 || points.length > 16) {
381
+ fail("curve points", points, "2 to 16 control points");
382
+ }
383
+ const flat = [];
384
+ let prevX = -1;
385
+ for (const [x, y] of points) {
386
+ intIn("curve point x", x, 0, 255);
387
+ intIn("curve point y", y, 0, 255);
388
+ if (x <= prevX) {
389
+ fail("curve points", points, "control points with strictly increasing x");
390
+ }
391
+ prevX = x;
392
+ flat.push(x, y);
393
+ }
394
+ return `curve(${channel},${flat.join(",")})`;
395
+ },
396
+ /**
397
+ * Convolution: apply a caller-supplied kernel, 9 values
398
+ * (3x3) or 25 (5x5) in row-major order, each a plain
399
+ * decimal from -1024 to 1024. With normalize set the
400
+ * server scales the kernel by the sum of its entries
401
+ * first (a zero sum applies the kernel as written). The
402
+ * edges replicate. `normalize` is a boolean or the 0/1
403
+ * flag itself.
404
+ */
405
+ convolution(values, normalize = false) {
406
+ if (values.length !== 9 && values.length !== 25) {
407
+ fail("convolution kernel", values, "9 (3x3) or 25 (5x5) values");
408
+ }
409
+ for (const v of values) {
410
+ floatIn("convolution kernel value", v, -1024, 1024);
411
+ if (!/^-?\d+(\.\d+)?$/.test(num(v))) {
412
+ fail("convolution kernel value", v, "a plain decimal (the grammar takes no exponent forms)");
413
+ }
414
+ }
415
+ if (normalize !== true &&
416
+ normalize !== false &&
417
+ normalize !== 0 &&
418
+ normalize !== 1) {
419
+ fail("convolution normalize", normalize, "a boolean or 0/1");
420
+ }
421
+ const flag = normalize === true || normalize === 1 ? 1 : 0;
422
+ return `convolution(${values.map(num).join(",")},${flag})`;
423
+ },
424
+ /**
425
+ * Film grain: one noise value per pixel, added equally
426
+ * to all three channels (alpha untouched), the value
427
+ * uniform in plus or minus the given percent of full
428
+ * scale. The field is deterministic, seeded from the
429
+ * image content and the amount, so the same request
430
+ * always renders the same bytes; 0 is a no-op.
431
+ */
432
+ noise(amount) {
433
+ return `noise(${intIn("noise amount", amount, 0, 100)})`;
434
+ },
435
+ /**
436
+ * Rotate by an angle in degrees (decimals allowed, no
437
+ * exponent spelling); multiples of 90 are exact quarter
438
+ * turns on the server.
439
+ */
440
+ rotate(angle) {
441
+ floatIn("rotate angle", angle, -36000, 36000);
442
+ if (!/^-?\d+(\.\d+)?$/.test(num(angle))) {
443
+ fail("rotate angle", angle, "a plain decimal angle (the grammar takes no exponent forms)");
444
+ }
445
+ return `rotate(${num(angle)})`;
446
+ },
447
+ /** Trim uniform borders; tolerance 0..255, default 10. */
448
+ trim(tolerance = 10) {
449
+ return `trim(${intIn("trim tolerance", tolerance, 0, 255)})`;
450
+ },
451
+ /** Trim uniform borders, then remove pixels per side (left, top, right, bottom). */
452
+ trimSides(tolerance, left, top, right, bottom) {
453
+ const side = (what, v) => intIn(what, v, 0, 4294967295);
454
+ return `trim(${intIn("trim tolerance", tolerance, 0, 255)},${side("trim left", left)},${side("trim top", top)},${side("trim right", right)},${side("trim bottom", bottom)})`;
455
+ },
456
+ /** Encoding quality 1..100, or `"auto"` for perceptual targeting. */
457
+ quality(value) {
458
+ if (value === "auto")
459
+ return "quality(auto)";
460
+ return `quality(${intIn("quality", value, 1, 100)})`;
461
+ },
462
+ /**
463
+ * Per-format quality in one URL: a map of format to value
464
+ * (1..100 or "auto"), plus an optional fallback for
465
+ * formats with no entry. Resolved by the server after
466
+ * format negotiation; entries spell in canonical
467
+ * (format-name) order with the fallback first.
468
+ */
469
+ qualityPerFormat(entries, fallback) {
470
+ const names = Object.keys(entries);
471
+ if (names.length === 0 && fallback === undefined) {
472
+ fail("quality", "{}", "at least one entry or a fallback");
473
+ }
474
+ const parts = [];
475
+ if (fallback !== undefined) {
476
+ parts.push(fallback === "auto" ? "auto" : String(intIn("quality", fallback, 1, 100)));
477
+ }
478
+ for (const name of names.sort()) {
479
+ if (!PER_FORMAT_QUALITY_FORMATS.includes(name)) {
480
+ fail("quality", name, `one of ${PER_FORMAT_QUALITY_FORMATS.join(", ")}`);
481
+ }
482
+ const value = entries[name];
483
+ parts.push(`${name}:${value === "auto" ? "auto" : intIn("quality", value, 1, 100)}`);
484
+ }
485
+ return `quality(${parts.join(",")})`;
486
+ },
487
+ /** Indexed PNG output with at most this many colors, 2..256; other formats ignore it. */
488
+ palette(colors) {
489
+ return `palette(${intIn("palette colors", colors, 2, 256)})`;
490
+ },
491
+ /**
492
+ * Output format, with its encoder options (issue #319):
493
+ * `progressive` and `subsampling` (444, 422, or 420) for
494
+ * JPEG, `interlace` for PNG, `method` (0..6) and `sns`
495
+ * (smart subsampling, 0..100) for WebP. An option its
496
+ * format cannot honour throws here, like the server's 400.
497
+ */
498
+ format(format, options = {}) {
499
+ if (!IMAGE_FORMATS.includes(format)) {
500
+ fail("format", format, `one of ${IMAGE_FORMATS.join(", ")}`);
501
+ }
502
+ // The output segment is the canonical spelling: the
503
+ // `jpg` input alias spells as `jpeg`, like the server's
504
+ // canonical form.
505
+ const canonical = format === "jpg" ? "jpeg" : format;
506
+ const args = [canonical];
507
+ const used = (key) => options[key] !== undefined;
508
+ if (format === "jpeg" || format === "jpg") {
509
+ if (used("interlace") || used("method") || used("sns")) {
510
+ fail("format", JSON.stringify(options), "jpeg takes progressive and subsampling only");
511
+ }
512
+ if (options.progressive)
513
+ args.push("progressive");
514
+ if (options.subsampling !== undefined) {
515
+ if (![444, 422, 420].includes(options.subsampling)) {
516
+ fail("subsampling", options.subsampling, "one of 444, 422, 420");
517
+ }
518
+ args.push(`subsampling:${options.subsampling}`);
519
+ }
520
+ }
521
+ else if (format === "png") {
522
+ if (used("progressive") || used("subsampling") || used("method") || used("sns")) {
523
+ fail("format", JSON.stringify(options), "png takes interlace only");
524
+ }
525
+ if (options.interlace)
526
+ args.push("interlace");
527
+ }
528
+ else if (format === "webp") {
529
+ if (used("progressive") || used("subsampling") || used("interlace")) {
530
+ fail("format", JSON.stringify(options), "webp takes method and sns only");
531
+ }
532
+ if (options.method !== undefined) {
533
+ args.push(`method:${intIn("method", options.method, 0, 6)}`);
534
+ }
535
+ if (options.sns !== undefined) {
536
+ args.push(`sns:${intIn("sns", options.sns, 0, 100)}`);
537
+ }
538
+ }
539
+ else if (used("progressive") ||
540
+ used("subsampling") ||
541
+ used("interlace") ||
542
+ used("method") ||
543
+ used("sns")) {
544
+ fail("format", JSON.stringify(options), `${format} takes no encoder options`);
545
+ }
546
+ return `format(${args.join(",")})`;
547
+ },
548
+ /** The background color other operations pad with (RRGGBB). */
549
+ fill(color) {
550
+ return `fill(${hex6("fill color", color)})`;
551
+ },
552
+ /** How much a face crop expands around the face: 0..3. */
553
+ facePad(amount) {
554
+ return `facepad(${num(floatIn("facepad", amount, 0, 3))})`;
555
+ },
556
+ /**
557
+ * Studio mode: `studio(product)` composites the subject
558
+ * the server's segmentation model finds onto a backdrop
559
+ * with a synthesized contact shadow, scaled and centered
560
+ * to the pad margin; `studio(scene)` keeps the
561
+ * photograph's scene, reframing it on the detected
562
+ * subject and correcting light and color. See
563
+ * {@link StudioOptions} for the named arguments.
564
+ * Arguments spelled at their defaults (shadow `soft`,
565
+ * pad 10) are omitted, matching the server's canonical
566
+ * spelling, so `studio("product", { pad: 10 })` and
567
+ * `studio("product")` are the same string.
568
+ */
569
+ studio(mode, options = {}) {
570
+ if (!STUDIO_MODES.includes(mode)) {
571
+ fail("studio mode", mode, `one of ${STUDIO_MODES.join(", ")}`);
572
+ }
573
+ const { bg, shadow, pad } = options;
574
+ if (mode === "scene" && (bg !== undefined || shadow !== undefined)) {
575
+ fail("studio scene options", options, "pad only: bg and shadow are product arguments");
576
+ }
577
+ const parts = [mode];
578
+ if (mode === "product") {
579
+ if (bg !== undefined) {
580
+ const value = bg === "white" || bg === "brand" || bg === "none" ? bg : hex6("studio bg", bg);
581
+ parts.push(`bg:${value}`);
582
+ }
583
+ if (shadow !== undefined) {
584
+ if (!STUDIO_SHADOWS.includes(shadow)) {
585
+ fail("studio shadow", shadow, `one of ${STUDIO_SHADOWS.join(", ")}`);
586
+ }
587
+ if (shadow !== "soft")
588
+ parts.push(`shadow:${shadow}`);
589
+ }
590
+ }
591
+ if (pad !== undefined) {
592
+ intIn("studio pad", pad, 0, 40);
593
+ if (pad !== 10)
594
+ parts.push(`pad:${pad}`);
595
+ }
596
+ return `studio(${parts.join(",")})`;
597
+ },
598
+ /** AI upscale by the given factor. */
599
+ upscale(factor) {
600
+ if (factor !== 2 && factor !== 4) {
601
+ fail("upscale factor", factor, "2 or 4");
602
+ }
603
+ return `upscale(${factor})`;
604
+ },
605
+ /** Device pixel ratio the sizes are multiplied by. */
606
+ dpr(factor) {
607
+ if (![1, 1.5, 2, 3].includes(factor)) {
608
+ fail("dpr", factor, "1, 1.5, 2, or 3");
609
+ }
610
+ return `dpr(${num(factor)})`;
611
+ },
612
+ /** Cap the output bytes, lowering quality to fit: at least 1. */
613
+ maxBytes(bytes) {
614
+ if (!Number.isSafeInteger(bytes) || bytes < 1) {
615
+ fail("max_bytes", bytes, "a positive integer byte budget");
616
+ }
617
+ return `max_bytes(${bytes})`;
618
+ },
619
+ /** Round the corners: one radius for all, or [tl, tr, br, bl]. */
620
+ radius(value) {
621
+ const corners = Array.isArray(value) ? value : [value, value, value, value];
622
+ for (const c of corners)
623
+ intIn("radius", c, 0, MAX_DIMENSION);
624
+ return `radius(${corners.join(",")})`;
625
+ },
626
+ /** Paint an opaque border inside the frame (RRGGBB); a width of 0 is a no-op. */
627
+ border(width, color) {
628
+ return `border(${intIn("border width", width, 0, MAX_DIMENSION)},${hex6("border color", color)})`;
629
+ },
630
+ mask(shape) {
631
+ if (shape !== "circle" && shape !== "ellipse") {
632
+ fail("mask shape", shape, '"circle" or "ellipse"');
633
+ }
634
+ return `mask(${shape})`;
635
+ },
636
+ duotone(shadow, highlight) {
637
+ return `duotone(${hex6("duotone shadow", shadow)},${hex6("duotone highlight", highlight)})`;
638
+ },
639
+ monochrome(color) {
640
+ return `monochrome(${hex6("monochrome color", color)})`;
641
+ },
642
+ /** Mosaic block size in pixels: 1..16383. */
643
+ pixelate(blockSize) {
644
+ return `pixelate(${intIn("pixelate size", blockSize, 1, MAX_DIMENSION)})`;
645
+ },
646
+ flip(axis) {
647
+ if (axis !== "h" && axis !== "v") {
648
+ fail("flip axis", axis, '"h" or "v"');
649
+ }
650
+ return `flip(${axis})`;
651
+ },
652
+ /** Overlay a watermark image at (x, y), opacity 0..100. */
653
+ watermark(url, x, y, alpha) {
654
+ intIn("watermark x", x, -2147483648, 2147483647);
655
+ intIn("watermark y", y, -2147483648, 2147483647);
656
+ intIn("watermark alpha", alpha, 0, 100);
657
+ if (url === "")
658
+ fail("watermark url", url, "a non-empty URL");
659
+ return `watermark(${encodeArg(url)},${x},${y},${alpha})`;
660
+ },
661
+ /**
662
+ * Composite another image over the result at (x, y) with
663
+ * opacity 0..100 and a blend mode; `widthPct` optionally
664
+ * scales it to that percent of the base width (1..400).
665
+ */
666
+ overlay(url, x, y, alpha, blend, widthPct) {
667
+ intIn("overlay x", x, -2147483648, 2147483647);
668
+ intIn("overlay y", y, -2147483648, 2147483647);
669
+ intIn("overlay alpha", alpha, 0, 100);
670
+ if (!BLEND_MODES.includes(blend)) {
671
+ fail("overlay blend", blend, `one of ${BLEND_MODES.join(", ")}`);
672
+ }
673
+ if (url === "")
674
+ fail("overlay url", url, "a non-empty URL");
675
+ const width = widthPct === undefined ? "" : `,${intIn("overlay width", widthPct, 1, 400)}`;
676
+ return `overlay(${encodeArg(url)},${x},${y},${alpha},${blend}${width})`;
677
+ },
678
+ /**
679
+ * Draw a text overlay. Color is RRGGBB or RRGGBBAA; the
680
+ * canonical spelling is always eight lowercase hex digits.
681
+ */
682
+ text(content, size, color, anchor) {
683
+ if (!ANCHORS.includes(anchor)) {
684
+ fail("text anchor", anchor, `one of ${ANCHORS.join(", ")}`);
685
+ }
686
+ if (content === "")
687
+ fail("text", content, "a non-empty label");
688
+ intIn("text size", size, 1, 1000);
689
+ return `text(${encodeArg(content)},${size},${hex6or8("text color", color)},${anchor})`;
690
+ },
691
+ /** Blur every detected object of the named class. */
692
+ blurClass(name) {
693
+ return `blurclass(${className("blurclass name", name)})`;
694
+ },
695
+ /** Pixelate every detected object of the named class. */
696
+ pixelateClass(name) {
697
+ return `pixelateclass(${className("pixelateclass name", name)})`;
698
+ },
699
+ /** Recolor every detected object of the named class to the given RRGGBB color. */
700
+ recolorClass(name, color) {
701
+ return `recolorclass(${className("recolorclass name", name)},${hex6("recolorclass color", color)})`;
702
+ },
703
+ /** Blur the rectangle (x, y, w, h) in pixels. */
704
+ blurRegion(x, y, w, h) {
705
+ return `blur_region(${region(x, y, w, h)})`;
706
+ },
707
+ /** Pixelate the rectangle (x, y, w, h) in pixels. */
708
+ pixelateRegion(x, y, w, h) {
709
+ return `pixelate_region(${region(x, y, w, h)})`;
710
+ },
711
+ /** Erase the rectangle (x, y, w, h) in pixels and inpaint it (AI). */
712
+ removeRegion(x, y, w, h) {
713
+ return `remove_region(${region(x, y, w, h)})`;
714
+ },
715
+ };
716
+ function region(x, y, w, h) {
717
+ intIn("region x", x, 0, MAX_DIMENSION);
718
+ intIn("region y", y, 0, MAX_DIMENSION);
719
+ intIn("region width", w, 1, MAX_DIMENSION);
720
+ intIn("region height", h, 1, MAX_DIMENSION);
721
+ return `${x},${y},${w},${h}`;
722
+ }