@crabcrop/url 0.9.4 → 0.9.6

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.
package/dist/explain.js CHANGED
@@ -24,6 +24,7 @@ export const FILTER_DESCRIPTIONS = {
24
24
  pixelateclass: "pixelate every detected object of the named class (needs a detection model on the server)",
25
25
  recolorclass: "recolor every detected object of the named class to the given color (needs a detection model on the server)",
26
26
  removebg: "remove the background (needs an AI model on the server)",
27
+ studio: "studio mode: `product` composites the subject onto a backdrop (bg: white, a RRGGBB color, brand, or none) with a synthesized contact shadow (shadow: soft, strong, or none), scaled and centered to a pad margin (pad: 0..40, default 10); `scene` keeps the photograph's scene, reframing it on the detected subject with light and color correction (pad only) (needs an AI model on the server)",
27
28
  keep_profile: "keep the source color profile instead of converting to sRGB",
28
29
  upscale: "AI upscale by the given factor (needs an AI model on the server)",
29
30
  equalize: "histogram equalization",
@@ -230,6 +231,55 @@ function validateFilter(name, args) {
230
231
  return args !== null && /^[+-]?\d+$/.test(args) && (Number(args) === 2 || Number(args) === 4)
231
232
  ? null
232
233
  : bad;
234
+ case "studio": {
235
+ // The server's studio grammar (url.rs parse_studio):
236
+ // the mode (`product` or `scene`) first, then named
237
+ // `key:value` arguments, each key at most once.
238
+ // Product takes `bg`, `shadow`, and `pad`; scene
239
+ // takes `pad` only, because a backdrop and a shadow
240
+ // are product concepts (naming one under scene is a
241
+ // bad argument, not a silent no-op).
242
+ if (args === null)
243
+ return bad;
244
+ const parts = args.split(",");
245
+ const mode = parts[0];
246
+ if (mode !== "product" && mode !== "scene")
247
+ return bad;
248
+ const seen = new Set();
249
+ for (const part of parts.slice(1)) {
250
+ const cut = part.indexOf(":");
251
+ if (cut === -1)
252
+ return bad;
253
+ const key = part.slice(0, cut);
254
+ const value = part.slice(cut + 1);
255
+ if (seen.has(key))
256
+ return bad;
257
+ seen.add(key);
258
+ if (key === "pad") {
259
+ // The pad parses as a Rust u8 (an optional `+`,
260
+ // then digits; no minus sign, not even `-0`) and
261
+ // is bounded to 40.
262
+ if (!/^\+?\d+$/.test(value) || BigInt(value) > 40n)
263
+ return bad;
264
+ }
265
+ else if (mode === "product" && key === "bg") {
266
+ if (value !== "white" &&
267
+ value !== "brand" &&
268
+ value !== "none" &&
269
+ !/^[0-9a-fA-F]{6}$/.test(value)) {
270
+ return bad;
271
+ }
272
+ }
273
+ else if (mode === "product" && key === "shadow") {
274
+ if (value !== "none" && value !== "soft" && value !== "strong")
275
+ return bad;
276
+ }
277
+ else {
278
+ return bad;
279
+ }
280
+ }
281
+ return null;
282
+ }
233
283
  case "dpr":
234
284
  return args !== null && isFloat(args) && [1, 1.5, 2, 3].includes(Number(args))
235
285
  ? null
@@ -394,9 +444,30 @@ function validateFilter(name, args) {
394
444
  }
395
445
  }
396
446
  function explainFilters(rest) {
397
- // The server splits the list naively on ':'; a ':' inside
398
- // parentheses is not special there either.
399
- const parts = rest.split(":");
447
+ // The server splits the list on the ':' separators that
448
+ // sit outside parentheses (url.rs split_filter_chain):
449
+ // an argument list may itself contain ':' (the studio
450
+ // filter's named arguments are `key:value`), so a naive
451
+ // split would cut those filters apart. Unbalanced
452
+ // parentheses leave the tail in one part, which then
453
+ // fails its own parse, as on the server.
454
+ const parts = [];
455
+ let depth = 0;
456
+ let start = 0;
457
+ for (let i = 0; i < rest.length; i++) {
458
+ const c = rest[i];
459
+ if (c === "(") {
460
+ depth += 1;
461
+ }
462
+ else if (c === ")") {
463
+ depth = Math.max(0, depth - 1);
464
+ }
465
+ else if (c === ":" && depth === 0) {
466
+ parts.push(rest.slice(start, i));
467
+ start = i + 1;
468
+ }
469
+ }
470
+ parts.push(rest.slice(start));
400
471
  const blurbs = [];
401
472
  for (const part of parts) {
402
473
  const match = part.match(/^([a-z_0-9]+)(?:\((.*)\))?$/);
package/dist/index.d.ts CHANGED
@@ -146,7 +146,7 @@ export { explainUrl } from "./explain.ts";
146
146
  export { FILTER_DESCRIPTIONS } from "./explain.ts";
147
147
  export type { ExplainedSegment, Explanation, SegmentKind, SignatureKind } from "./explain.ts";
148
148
  export { filter, joinOps, ops } from "./operations.ts";
149
- export type { Anchor, BlendMode, CropAlign, CurveChannel, Dimension, ImageFormat, MaskShape, } from "./operations.ts";
149
+ export type { Anchor, BlendMode, CropAlign, CurveChannel, Dimension, ImageFormat, MaskShape, StudioMode, StudioOptions, StudioShadow, } from "./operations.ts";
150
150
  /**
151
151
  * Verify a URL's signature locally. Returns true or false, or
152
152
  * null when the URL is unsigned or malformed.
@@ -23,6 +23,36 @@ export type BlendMode = "normal" | "multiply" | "screen" | "overlay";
23
23
  export type MaskShape = "circle" | "ellipse";
24
24
  /** Channels the `curve(...)` filter remaps. */
25
25
  export type CurveChannel = "rgb" | "r" | "g" | "b";
26
+ /** Modes the `studio(...)` filter runs. */
27
+ export type StudioMode = "product" | "scene";
28
+ /** Contact shadow strengths for `studio(product, ...)`. */
29
+ export type StudioShadow = "soft" | "strong" | "none";
30
+ /**
31
+ * Named arguments for the `studio(...)` filter. `bg` and
32
+ * `shadow` are product arguments only: the server rejects
33
+ * them under `scene`, so the builder throws for them there.
34
+ */
35
+ export interface StudioOptions {
36
+ /**
37
+ * The product backdrop: `"white"`, `"brand"` (the
38
+ * operator brand color, white when none is configured),
39
+ * `"none"` (the subject keeps its transparency and no
40
+ * shadow is synthesized), or a RRGGBB hex color. Unset
41
+ * means the unnamed default: the brand color when one
42
+ * is configured, else white. Naming `"white"` is not
43
+ * the default: the two can resolve differently, so they
44
+ * spell differently.
45
+ */
46
+ bg?: string;
47
+ /** Contact shadow strength; the default is `"soft"`. */
48
+ shadow?: StudioShadow;
49
+ /**
50
+ * Pad margin in percent, 0..40; the default is 10.
51
+ * Under `scene` it is the margin the reframed subject
52
+ * keeps.
53
+ */
54
+ pad?: number;
55
+ }
26
56
  /**
27
57
  * One side of a size: a pixel count (1..16383), 0 for
28
58
  * proportional, a negative count to flip that axis, or
@@ -138,6 +168,20 @@ export declare const filter: {
138
168
  fill(color: string): string;
139
169
  /** How much a face crop expands around the face: 0..3. */
140
170
  facePad(amount: number): string;
171
+ /**
172
+ * Studio mode: `studio(product)` composites the subject
173
+ * the server's segmentation model finds onto a backdrop
174
+ * with a synthesized contact shadow, scaled and centered
175
+ * to the pad margin; `studio(scene)` keeps the
176
+ * photograph's scene, reframing it on the detected
177
+ * subject and correcting light and color. See
178
+ * {@link StudioOptions} for the named arguments.
179
+ * Arguments spelled at their defaults (shadow `soft`,
180
+ * pad 10) are omitted, matching the server's canonical
181
+ * spelling, so `studio("product", { pad: 10 })` and
182
+ * `studio("product")` are the same string.
183
+ */
184
+ studio(mode: StudioMode, options?: StudioOptions): string;
141
185
  /** AI upscale by the given factor. */
142
186
  upscale(factor: 2 | 4): string;
143
187
  /** Device pixel ratio the sizes are multiplied by. */
@@ -113,6 +113,8 @@ const ANCHORS = [
113
113
  ];
114
114
  const BLEND_MODES = ["normal", "multiply", "screen", "overlay"];
115
115
  const CURVE_CHANNELS = ["rgb", "r", "g", "b"];
116
+ const STUDIO_MODES = ["product", "scene"];
117
+ const STUDIO_SHADOWS = ["soft", "strong", "none"];
116
118
  const IMAGE_FORMATS = ["jpeg", "jpg", "png", "webp", "jxl", "avif", "gif", "mp4", "webm"];
117
119
  /** Operation segments, one typed call per segment kind. */
118
120
  export const ops = {
@@ -379,6 +381,48 @@ export const filter = {
379
381
  facePad(amount) {
380
382
  return `facepad(${num(floatIn("facepad", amount, 0, 3))})`;
381
383
  },
384
+ /**
385
+ * Studio mode: `studio(product)` composites the subject
386
+ * the server's segmentation model finds onto a backdrop
387
+ * with a synthesized contact shadow, scaled and centered
388
+ * to the pad margin; `studio(scene)` keeps the
389
+ * photograph's scene, reframing it on the detected
390
+ * subject and correcting light and color. See
391
+ * {@link StudioOptions} for the named arguments.
392
+ * Arguments spelled at their defaults (shadow `soft`,
393
+ * pad 10) are omitted, matching the server's canonical
394
+ * spelling, so `studio("product", { pad: 10 })` and
395
+ * `studio("product")` are the same string.
396
+ */
397
+ studio(mode, options = {}) {
398
+ if (!STUDIO_MODES.includes(mode)) {
399
+ fail("studio mode", mode, `one of ${STUDIO_MODES.join(", ")}`);
400
+ }
401
+ const { bg, shadow, pad } = options;
402
+ if (mode === "scene" && (bg !== undefined || shadow !== undefined)) {
403
+ fail("studio scene options", options, "pad only: bg and shadow are product arguments");
404
+ }
405
+ const parts = [mode];
406
+ if (mode === "product") {
407
+ if (bg !== undefined) {
408
+ const value = bg === "white" || bg === "brand" || bg === "none" ? bg : hex6("studio bg", bg);
409
+ parts.push(`bg:${value}`);
410
+ }
411
+ if (shadow !== undefined) {
412
+ if (!STUDIO_SHADOWS.includes(shadow)) {
413
+ fail("studio shadow", shadow, `one of ${STUDIO_SHADOWS.join(", ")}`);
414
+ }
415
+ if (shadow !== "soft")
416
+ parts.push(`shadow:${shadow}`);
417
+ }
418
+ }
419
+ if (pad !== undefined) {
420
+ intIn("studio pad", pad, 0, 40);
421
+ if (pad !== 10)
422
+ parts.push(`pad:${pad}`);
423
+ }
424
+ return `studio(${parts.join(",")})`;
425
+ },
382
426
  /** AI upscale by the given factor. */
383
427
  upscale(factor) {
384
428
  if (factor !== 2 && factor !== 4) {
package/package.json CHANGED
@@ -21,7 +21,7 @@
21
21
  "test": "node --test"
22
22
  },
23
23
  "type": "module",
24
- "version": "0.9.4",
24
+ "version": "0.9.6",
25
25
  "devDependencies": {
26
26
  "@types/node": "^26.6.5",
27
27
  "typescript": "^7.0.2"