@crabcrop/url 0.9.8 → 0.9.10

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/README.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # @crabcrop/url
2
2
 
3
- Build and sign [crabcrop](https://github.com/dayvson/crabcrop) URLs from TypeScript or JavaScript. Standard library only (`node:crypto`); the signing scheme is specified in [`spec/url-signing.md`](../../spec/url-signing.md). Signing is pinned by the canonical [`spec/test-vectors.json`](../../spec/test-vectors.json), which this package runs as tests, and the explainer's verdicts are pinned by a grammar corpus mirrored in the playground's test suite.
3
+ Build and sign [crabcrop](https://github.com/dayvson/crabcrop) URLs from TypeScript or JavaScript. Standard library only (`node:crypto`); the signing scheme is specified in [`spec/url-signing.md`](../../spec/url-signing.md). Signing is pinned by the canonical [`spec/test-vectors.json`](../../spec/test-vectors.json), which this package runs as tests, and the explainer's verdicts and the typed builders are pinned by the shared grammar corpora in [`spec/explain-verdicts.json`](../../spec/explain-verdicts.json) and [`spec/operation-vectors.json`](../../spec/operation-vectors.json), which the playground's suite and the server crate's differential tests run as well.
4
4
 
5
5
  ## Usage
6
6
 
package/dist/explain.js CHANGED
@@ -186,6 +186,11 @@ function validateFilter(name, args) {
186
186
  : bad;
187
187
  }
188
188
  case "blur":
189
+ // The server's blur bound (url.rs MAX_BLUR_SIGMA):
190
+ // positive and at most 512.
191
+ return args !== null && isFloat(args) && Number(args) > 0 && Number(args) <= 512
192
+ ? null
193
+ : bad;
189
194
  case "sharpen":
190
195
  return args !== null && isFloat(args) && Number(args) > 0 ? null : bad;
191
196
  case "brighten":
@@ -410,7 +415,7 @@ function validateFilter(name, args) {
410
415
  return bad;
411
416
  const parts = args.split(",");
412
417
  return parts.length === 2 &&
413
- isIntIn(parts[0], 1, 16383) &&
418
+ isIntIn(parts[0], 0, 16383) &&
414
419
  /^[0-9a-fA-F]{6}$/.test(parts[1])
415
420
  ? null
416
421
  : bad;
@@ -714,6 +719,42 @@ function explainSegment(seg, nowSeconds) {
714
719
  detail: "the response is a diagnostic image instead of the transform result: the canvas the next crop operates on, with the chosen focal point (magenta crosshair), the focal rectangle when one is in play, the detection boxes that fed the decision (amber), and the crop window outline (blue); with no crop it shows the focal analysis of the final image; debug responses are never cached and are served with Cache-Control: no-store; animated sources and video formats are refused with 400",
715
720
  };
716
721
  }
722
+ if (seg.startsWith("frame:")) {
723
+ const rest = seg.slice(6);
724
+ // The server's frame grammar (url.rs parse_frame): the
725
+ // poster keyword, or a strict decimal (no sign, no
726
+ // exponent, no leading dot) as seconds up to 86400 or,
727
+ // with a % suffix, as a percent up to 100.
728
+ const decimal = (text, max) => /^\d+(\.\d+)?$/.test(text) && Number(text) <= max;
729
+ if (rest === "poster") {
730
+ return { kind: "operation", title: "Frame", detail: "render the video source's poster frame" };
731
+ }
732
+ if (rest.endsWith("%") && decimal(rest.slice(0, -1), 100)) {
733
+ return { kind: "operation", title: "Frame", detail: `render the frame ${rest} through the video source` };
734
+ }
735
+ if (!rest.endsWith("%") && decimal(rest, 86400)) {
736
+ return { kind: "operation", title: "Frame", detail: `render the frame at ${rest} seconds into the video source` };
737
+ }
738
+ return {
739
+ kind: "operation",
740
+ title: "Frame",
741
+ error: `malformed frame segment: ${seg} (want frame:poster, frame:<seconds> up to 86400, or frame:<percent>% up to 100; the server answers 400)`,
742
+ };
743
+ }
744
+ if (seg.startsWith("page:")) {
745
+ const rest = seg.slice(5);
746
+ // The server's page grammar (url.rs parse_page): ASCII
747
+ // digits, leading zeros allowed, 1 to 999999.
748
+ const digits = rest.replace(/^0+/, "");
749
+ if (!/^\d+$/.test(rest) || digits === "" || digits.length > 6) {
750
+ return {
751
+ kind: "operation",
752
+ title: "Page",
753
+ error: `malformed page segment: ${seg} (want page:<n> with n from 1 to 999999; the server answers 400)`,
754
+ };
755
+ }
756
+ return { kind: "operation", title: "Page", detail: `render page ${Number(digits)} of the PDF source` };
757
+ }
717
758
  if (seg.startsWith("preset:")) {
718
759
  const name = seg.slice(7);
719
760
  if (!name) {
@@ -841,8 +882,41 @@ function explainSegment(seg, nowSeconds) {
841
882
  if (parseSizeSegment(seg)) {
842
883
  return { kind: "operation", title: "Resize", detail: sizeBlurb(seg) };
843
884
  }
885
+ if (isSizeShaped(seg)) {
886
+ // The server's dispatch (url.rs size_shaped, issue #228):
887
+ // a segment shaped like a size that fails the size
888
+ // grammar is a malformed size, not the start of the
889
+ // source, so the request is a 400 rather than a fetch
890
+ // of a nonsense source.
891
+ return {
892
+ kind: "operation",
893
+ title: "Resize",
894
+ error: `malformed size segment: ${seg} (each side is a pixel count up to ${MAX_DIMENSION}, 0, or orig; the server answers 400)`,
895
+ };
896
+ }
844
897
  return null; // Not an operation: the source starts here.
845
898
  }
899
+ /**
900
+ * The server's size-shape test (url.rs size_shaped), ported:
901
+ * an `x` joining two parts, at least one of them a dimension
902
+ * spelling (digits, `orig`, or empty, with an optional flip
903
+ * sign), and no `.` or `:` anywhere, the punctuation that
904
+ * marks URL text.
905
+ */
906
+ function isSizeShaped(seg) {
907
+ const x = seg.indexOf("x");
908
+ if (x === -1)
909
+ return false;
910
+ const left = seg.slice(0, x);
911
+ const right = seg.slice(x + 1);
912
+ if (left.includes(".") || right.includes(".") || seg.includes(":"))
913
+ return false;
914
+ const spelling = (part) => {
915
+ const digits = part.startsWith("-") ? part.slice(1) : part;
916
+ return digits === "" || digits === "orig" || /^\d+$/.test(digits);
917
+ };
918
+ return spelling(left) || spelling(right);
919
+ }
846
920
  /**
847
921
  * Parse a crabcrop URL (or bare path) back into its pieces,
848
922
  * explaining each segment. Mirrors the server's dispatch:
@@ -142,7 +142,7 @@ export declare const filter: {
142
142
  sepia(): string;
143
143
  blurFaces(): string;
144
144
  pixelateFaces(): string;
145
- /** Gaussian blur by sigma (positive). */
145
+ /** Gaussian blur by sigma: positive, at most the server's 512 cap. */
146
146
  blur(sigma: number): string;
147
147
  /** Unsharp-mask strength (positive). */
148
148
  sharpen(amount: number): string;
@@ -247,7 +247,7 @@ export declare const filter: {
247
247
  maxBytes(bytes: number): string;
248
248
  /** Round the corners: one radius for all, or [tl, tr, br, bl]. */
249
249
  radius(value: number | [number, number, number, number]): string;
250
- /** Paint an opaque border inside the frame (RRGGBB). */
250
+ /** Paint an opaque border inside the frame (RRGGBB); a width of 0 is a no-op. */
251
251
  border(width: number, color: string): string;
252
252
  mask(shape: MaskShape): string;
253
253
  duotone(shadow: string, highlight: string): string;
@@ -306,9 +306,12 @@ export const filter = {
306
306
  pixelateFaces() {
307
307
  return "pixelatefaces";
308
308
  },
309
- /** Gaussian blur by sigma (positive). */
309
+ /** Gaussian blur by sigma: positive, at most the server's 512 cap. */
310
310
  blur(sigma) {
311
- return `blur(${num(positiveFloat("blur sigma", sigma))})`;
311
+ if (!Number.isFinite(sigma) || sigma <= 0 || sigma > 512) {
312
+ fail("blur sigma", sigma, "a positive number up to 512");
313
+ }
314
+ return `blur(${num(sigma)})`;
312
315
  },
313
316
  /** Unsharp-mask strength (positive). */
314
317
  sharpen(amount) {
@@ -489,7 +492,11 @@ export const filter = {
489
492
  if (!IMAGE_FORMATS.includes(format)) {
490
493
  fail("format", format, `one of ${IMAGE_FORMATS.join(", ")}`);
491
494
  }
492
- const args = [format];
495
+ // The output segment is the canonical spelling: the
496
+ // `jpg` input alias spells as `jpeg`, like the server's
497
+ // canonical form.
498
+ const canonical = format === "jpg" ? "jpeg" : format;
499
+ const args = [canonical];
493
500
  const used = (key) => options[key] !== undefined;
494
501
  if (format === "jpeg" || format === "jpg") {
495
502
  if (used("interlace") || used("method") || used("sns")) {
@@ -609,9 +616,9 @@ export const filter = {
609
616
  intIn("radius", c, 0, MAX_DIMENSION);
610
617
  return `radius(${corners.join(",")})`;
611
618
  },
612
- /** Paint an opaque border inside the frame (RRGGBB). */
619
+ /** Paint an opaque border inside the frame (RRGGBB); a width of 0 is a no-op. */
613
620
  border(width, color) {
614
- return `border(${intIn("border width", width, 1, MAX_DIMENSION)},${hex6("border color", color)})`;
621
+ return `border(${intIn("border width", width, 0, MAX_DIMENSION)},${hex6("border color", color)})`;
615
622
  },
616
623
  mask(shape) {
617
624
  if (shape !== "circle" && shape !== "ellipse") {
package/package.json CHANGED
@@ -21,7 +21,7 @@
21
21
  "test": "node --test"
22
22
  },
23
23
  "type": "module",
24
- "version": "0.9.8",
24
+ "version": "0.9.10",
25
25
  "devDependencies": {
26
26
  "@types/node": "^26.6.5",
27
27
  "typescript": "^7.0.2"