@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,285 @@
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
+ /** Output formats the `format(...)` filter accepts. */
15
+ export type ImageFormat = "jpeg" | "jpg" | "png" | "webp" | "jxl" | "avif" | "gif" | "mp4" | "webm";
16
+ /** Formats a per-format quality entry can name (the video formats take no quality). */
17
+ export type PerFormatQualityFormat = "jpeg" | "png" | "webp" | "jxl" | "avif" | "gif";
18
+ /** Per-format encoder options for the `format(...)` filter (issue #319). */
19
+ export interface FormatOptions {
20
+ /** JPEG: progressive (multi-scan) encoding. */
21
+ progressive?: boolean;
22
+ /** JPEG: chroma subsampling, 444, 422, or 420. */
23
+ subsampling?: 444 | 422 | 420;
24
+ /** PNG: Adam7 interlacing. */
25
+ interlace?: boolean;
26
+ /** WebP: libwebp compression method, 0..6. */
27
+ method?: number;
28
+ /** WebP: smart subsampling strength, 0..100. */
29
+ sns?: number;
30
+ }
31
+ /** Crop alignments; `center` is the bare `crop:WxH` spelling. */
32
+ export type CropAlign = "center" | "smart" | "face" | "top" | "bottom" | "left" | "right" | "top-left" | "top-right" | "bottom-left" | "bottom-right";
33
+ /** Text-overlay anchor points. */
34
+ export type Anchor = "top-left" | "top-center" | "top-right" | "center-left" | "center" | "center-right" | "bottom-left" | "bottom-center" | "bottom-right";
35
+ /** Overlay blend modes. */
36
+ export type BlendMode = "normal" | "multiply" | "screen" | "overlay";
37
+ /** Mask shapes for the `mask(...)` filter. */
38
+ export type MaskShape = "circle" | "ellipse";
39
+ /** Channels the `curve(...)` filter remaps. */
40
+ export type CurveChannel = "rgb" | "r" | "g" | "b";
41
+ /** Modes the `studio(...)` filter runs. */
42
+ export type StudioMode = "product" | "scene";
43
+ /** Contact shadow strengths for `studio(product, ...)`. */
44
+ export type StudioShadow = "soft" | "strong" | "none";
45
+ /**
46
+ * Named arguments for the `studio(...)` filter. `bg` and
47
+ * `shadow` are product arguments only: the server rejects
48
+ * them under `scene`, so the builder throws for them there.
49
+ */
50
+ export interface StudioOptions {
51
+ /**
52
+ * The product backdrop: `"white"`, `"brand"` (the
53
+ * operator brand color, white when none is configured),
54
+ * `"none"` (the subject keeps its transparency and no
55
+ * shadow is synthesized), or a RRGGBB hex color. Unset
56
+ * means the unnamed default: the brand color when one
57
+ * is configured, else white. Naming `"white"` is not
58
+ * the default: the two can resolve differently, so they
59
+ * spell differently.
60
+ */
61
+ bg?: string;
62
+ /** Contact shadow strength; the default is `"soft"`. */
63
+ shadow?: StudioShadow;
64
+ /**
65
+ * Pad margin in percent, 0..40; the default is 10.
66
+ * Under `scene` it is the margin the reframed subject
67
+ * keeps.
68
+ */
69
+ pad?: number;
70
+ }
71
+ /**
72
+ * One side of a size: a pixel count (1..16383), 0 for
73
+ * proportional, a negative count to flip that axis, or
74
+ * `"orig"` for the source's own dimension.
75
+ */
76
+ export type Dimension = number | "orig";
77
+ /** Operation segments, one typed call per segment kind. */
78
+ export declare const ops: {
79
+ /** `300x200`; each side a Dimension (0 proportional, negative flips). */
80
+ size(width: Dimension, height: Dimension): string;
81
+ /**
82
+ * `fit-in:300x200`; no flips (the server rejects them here).
83
+ * With `adaptive`, `fit-in:300x200:adaptive`: the box axes
84
+ * swap when the source orientation disagrees with the box's.
85
+ */
86
+ fitIn(width: Dimension, height: Dimension, adaptive?: boolean): string;
87
+ /** `crop:300x200` or `crop:300x200:smart`; an exact pixel box. */
88
+ crop(width: number, height: number, align?: CropAlign): string;
89
+ /**
90
+ * `crop:300x200:objects(person,car):1.5`; crops to the
91
+ * union of every detection of the named classes, the
92
+ * union box scaled about its center by `scale` (1 is the
93
+ * tight box; the crop stays centered on the union).
94
+ * Needs a detection model configured on the server; when
95
+ * none of the classes is detected the render falls back
96
+ * to the plain center crop of the same size. Duplicate
97
+ * classes (case-insensitive) are spelled once, as the
98
+ * server's canonical form spells them; at most 32
99
+ * distinct classes, and a 33rd throws, since the server
100
+ * rejects it with `invalid_crop`.
101
+ */
102
+ cropObjects(width: number, height: number, classes: string[], scale?: number): string;
103
+ /** `crop-rect:10x20:110x220` (left x top : right x bottom). */
104
+ cropRect(left: number, top: number, right: number, bottom: number): string;
105
+ /** `focal:10x20:110x220` (left x top : right x bottom); steers the next crop. */
106
+ focal(left: number, top: number, right: number, bottom: number): string;
107
+ /** `focalpoint:0.75x0.4:2` (fractions of the image dimensions, zoom optional); steers the next crop. */
108
+ focalPoint(x: number, y: number, zoom?: number): string;
109
+ /** `pad:300x200`, optionally `:blur` or a RRGGBB fill color. */
110
+ pad(width: number, height: number, fill?: "blur" | string): string;
111
+ /** `preset:thumb`; expands server-side. */
112
+ preset(name: string): string;
113
+ /**
114
+ * `maxage:60`; this response's Cache-Control lifetime in
115
+ * seconds (0 to 31536000), overriding the default year for
116
+ * this request only. Header-only: it never enters the
117
+ * cache key, so spellings that differ only here share one
118
+ * stored image.
119
+ */
120
+ maxage(seconds: number): string;
121
+ /**
122
+ * `debug:focal`; the smart-crop debug view. Place it
123
+ * before the crop it annotates: the response is a
124
+ * diagnostic image of the focal decision (focal point,
125
+ * focal rectangle, crop window drawn on the crop's
126
+ * canvas), never the transform result, and it is never
127
+ * cached (served with Cache-Control: no-store).
128
+ */
129
+ debugFocal(): string;
130
+ /** Join filter calls into one `filters:` segment. */
131
+ filters(...calls: string[]): string;
132
+ };
133
+ /** Join operation segments into the operations string `buildURL` takes. */
134
+ export declare function joinOps(...segments: string[]): string;
135
+ /** Filter calls for `ops.filters(...)`; each returns its canonical spelling. */
136
+ export declare const filter: {
137
+ grayscale(): string;
138
+ invert(): string;
139
+ noUpscale(): string;
140
+ equalize(): string;
141
+ enhance(): string;
142
+ removeBg(): string;
143
+ keepProfile(): string;
144
+ sepia(): string;
145
+ blurFaces(): string;
146
+ pixelateFaces(): string;
147
+ /** Gaussian blur by sigma: positive, at most the server's 512 cap. */
148
+ blur(sigma: number): string;
149
+ /** Unsharp-mask strength (positive). */
150
+ sharpen(amount: number): string;
151
+ /** Add to every channel: -255..255. */
152
+ brighten(amount: number): string;
153
+ /** Percent contrast: -100..100 (0 unchanged, -100 flat). */
154
+ contrast(percent: number): string;
155
+ /** Gamma correction divisor: 0 < g <= 10 (1 unchanged; above 1 brightens midtones). */
156
+ gamma(value: number): string;
157
+ /** Exposure in stops: -10..10 (0 unchanged; +1 doubles the light, -1 halves it). */
158
+ exposure(stops: number): string;
159
+ /** Highlights and shadows: two percents, each -100..100 (0 unchanged). */
160
+ highlightsShadows(highlights: number, shadows: number): string;
161
+ /** Vibrance percent: -100..100 (0 unchanged; muted colors move most, vivid colors are protected). */
162
+ vibrance(percent: number): string;
163
+ /** Rotate the hue by integer degrees. */
164
+ hueRotate(degrees: number): string;
165
+ /** Saturation factor: 0..255 (0 grayscale, 1 identity). */
166
+ saturation(factor: number): string;
167
+ /** Per-channel offsets, each -255..255. */
168
+ rgb(r: number, g: number, b: number): string;
169
+ /**
170
+ * Tone curve: remap the channel through 2 to 16 [x, y]
171
+ * control points, each coordinate 0..255 with x strictly
172
+ * increasing. Between points the server interpolates
173
+ * linearly; inputs outside the point range clamp to the
174
+ * nearest end value.
175
+ */
176
+ curve(channel: CurveChannel, points: [number, number][]): string;
177
+ /**
178
+ * Convolution: apply a caller-supplied kernel, 9 values
179
+ * (3x3) or 25 (5x5) in row-major order, each a plain
180
+ * decimal from -1024 to 1024. With normalize set the
181
+ * server scales the kernel by the sum of its entries
182
+ * first (a zero sum applies the kernel as written). The
183
+ * edges replicate. `normalize` is a boolean or the 0/1
184
+ * flag itself.
185
+ */
186
+ convolution(values: number[], normalize?: boolean | 0 | 1): string;
187
+ /**
188
+ * Film grain: one noise value per pixel, added equally
189
+ * to all three channels (alpha untouched), the value
190
+ * uniform in plus or minus the given percent of full
191
+ * scale. The field is deterministic, seeded from the
192
+ * image content and the amount, so the same request
193
+ * always renders the same bytes; 0 is a no-op.
194
+ */
195
+ noise(amount: number): string;
196
+ /**
197
+ * Rotate by an angle in degrees (decimals allowed, no
198
+ * exponent spelling); multiples of 90 are exact quarter
199
+ * turns on the server.
200
+ */
201
+ rotate(angle: number): string;
202
+ /** Trim uniform borders; tolerance 0..255, default 10. */
203
+ trim(tolerance?: number): string;
204
+ /** Trim uniform borders, then remove pixels per side (left, top, right, bottom). */
205
+ trimSides(tolerance: number, left: number, top: number, right: number, bottom: number): string;
206
+ /** Encoding quality 1..100, or `"auto"` for perceptual targeting. */
207
+ quality(value: number | "auto"): string;
208
+ /**
209
+ * Per-format quality in one URL: a map of format to value
210
+ * (1..100 or "auto"), plus an optional fallback for
211
+ * formats with no entry. Resolved by the server after
212
+ * format negotiation; entries spell in canonical
213
+ * (format-name) order with the fallback first.
214
+ */
215
+ qualityPerFormat(entries: Partial<Record<PerFormatQualityFormat, number | "auto">>, fallback?: number | "auto"): string;
216
+ /** Indexed PNG output with at most this many colors, 2..256; other formats ignore it. */
217
+ palette(colors: number): string;
218
+ /**
219
+ * Output format, with its encoder options (issue #319):
220
+ * `progressive` and `subsampling` (444, 422, or 420) for
221
+ * JPEG, `interlace` for PNG, `method` (0..6) and `sns`
222
+ * (smart subsampling, 0..100) for WebP. An option its
223
+ * format cannot honour throws here, like the server's 400.
224
+ */
225
+ format(format: ImageFormat, options?: FormatOptions): string;
226
+ /** The background color other operations pad with (RRGGBB). */
227
+ fill(color: string): string;
228
+ /** How much a face crop expands around the face: 0..3. */
229
+ facePad(amount: number): string;
230
+ /**
231
+ * Studio mode: `studio(product)` composites the subject
232
+ * the server's segmentation model finds onto a backdrop
233
+ * with a synthesized contact shadow, scaled and centered
234
+ * to the pad margin; `studio(scene)` keeps the
235
+ * photograph's scene, reframing it on the detected
236
+ * subject and correcting light and color. See
237
+ * {@link StudioOptions} for the named arguments.
238
+ * Arguments spelled at their defaults (shadow `soft`,
239
+ * pad 10) are omitted, matching the server's canonical
240
+ * spelling, so `studio("product", { pad: 10 })` and
241
+ * `studio("product")` are the same string.
242
+ */
243
+ studio(mode: StudioMode, options?: StudioOptions): string;
244
+ /** AI upscale by the given factor. */
245
+ upscale(factor: 2 | 4): string;
246
+ /** Device pixel ratio the sizes are multiplied by. */
247
+ dpr(factor: 1 | 1.5 | 2 | 3): string;
248
+ /** Cap the output bytes, lowering quality to fit: at least 1. */
249
+ maxBytes(bytes: number): string;
250
+ /** Round the corners: one radius for all, or [tl, tr, br, bl]. */
251
+ radius(value: number | [number, number, number, number]): string;
252
+ /** Paint an opaque border inside the frame (RRGGBB); a width of 0 is a no-op. */
253
+ border(width: number, color: string): string;
254
+ mask(shape: MaskShape): string;
255
+ duotone(shadow: string, highlight: string): string;
256
+ monochrome(color: string): string;
257
+ /** Mosaic block size in pixels: 1..16383. */
258
+ pixelate(blockSize: number): string;
259
+ flip(axis: "h" | "v"): string;
260
+ /** Overlay a watermark image at (x, y), opacity 0..100. */
261
+ watermark(url: string, x: number, y: number, alpha: number): string;
262
+ /**
263
+ * Composite another image over the result at (x, y) with
264
+ * opacity 0..100 and a blend mode; `widthPct` optionally
265
+ * scales it to that percent of the base width (1..400).
266
+ */
267
+ overlay(url: string, x: number, y: number, alpha: number, blend: BlendMode, widthPct?: number): string;
268
+ /**
269
+ * Draw a text overlay. Color is RRGGBB or RRGGBBAA; the
270
+ * canonical spelling is always eight lowercase hex digits.
271
+ */
272
+ text(content: string, size: number, color: string, anchor: Anchor): string;
273
+ /** Blur every detected object of the named class. */
274
+ blurClass(name: string): string;
275
+ /** Pixelate every detected object of the named class. */
276
+ pixelateClass(name: string): string;
277
+ /** Recolor every detected object of the named class to the given RRGGBB color. */
278
+ recolorClass(name: string, color: string): string;
279
+ /** Blur the rectangle (x, y, w, h) in pixels. */
280
+ blurRegion(x: number, y: number, w: number, h: number): string;
281
+ /** Pixelate the rectangle (x, y, w, h) in pixels. */
282
+ pixelateRegion(x: number, y: number, w: number, h: number): string;
283
+ /** Erase the rectangle (x, y, w, h) in pixels and inpaint it (AI). */
284
+ removeRegion(x: number, y: number, w: number, h: number): string;
285
+ };