@crabcrop/mcp 0.0.0-stage → 0.1.0

package/node_modules/@crabcrop/url/dist/explain.js

@@ -0,0 +1,654 @@
+/**
+ * Parse a crabcrop URL (or bare path) back into its pieces and
+ * explain each segment, mirroring the server's grammar. This is
+ * the canonical implementation: the playground keeps a plain-JS
+ * copy for its no-build static page, and both are pinned to the
+ * same verdict corpus (audit PL-10, P-3).
+ */
+export const FILTER_DESCRIPTIONS = {
+    grayscale: "convert to grayscale",
+    invert: "invert the colors",
+    no_upscale: "never enlarge the source",
+    blur: "gaussian blur, argument is the sigma",
+    blurfaces: "blur detected faces (needs a face model on the server)",
+    brighten: "brighten by the given amount (-255..255)",
+    contrast: "contrast in percent, -100..100 (0 is unchanged, -100 is flat)",
+    huerotate: "rotate the hue by the given degrees",
+    rotate: "rotate by the given angle in degrees; the canvas expands to fit",
+    quality: "output quality 1..100, or `auto` for perceptual targeting",
+    format: "force the output format",
+    fill: "the background color other operations pad with",
+    facepad: "how much a face crop expands around the face",
+    pixelatefaces: "pixelate detected faces (needs a face model on the server)",
+    blurclass: "blur every detected object of the named class (needs a detection model on the server)",
+    pixelateclass: "pixelate every detected object of the named class (needs a detection model on the server)",
+    removebg: "remove the background (needs an AI model on the server)",
+    keep_profile: "keep the source color profile instead of converting to sRGB",
+    upscale: "AI upscale by the given factor (needs an AI model on the server)",
+    equalize: "histogram equalization",
+    saturation: "saturation factor, 0..255 (0 is grayscale, 1 is identity)",
+    sharpen: "sharpen by the given amount",
+    text: "draw a text overlay (needs a font on the server)",
+    rgb: "tint toward the given red/green/blue amounts",
+    curve: "tone curve: remap the named channel (rgb, r, g, or b) through 2 to 16 x,y control points, linearly interpolated, ends clamped",
+    convolution: "convolve with a 3x3 or 5x5 kernel: 9 or 25 row-major values (plain decimals, -1024..1024), then a normalize flag (0 or 1); edges replicate",
+    noise: "add monochrome film grain: one deterministic noise value per pixel on all channels, strength 0..100 percent of full scale (0 is a no-op)",
+    trim: "trim uniform borders",
+    dpr: "device pixel ratio the sizes are multiplied by",
+    watermark: "overlay a watermark image",
+    max_bytes: "cap the output size, lowering quality to fit",
+    radius: "round the corners by the given radius in pixels (one value, or four in CSS corner order); needs an alpha-capable format",
+    border: "paint a border of the given width and color (RRGGBB) inside the frame",
+    mask: "keep only the inscribed `circle` or `ellipse`; the rest becomes transparent",
+    sepia: "the classic warm sepia tone",
+    duotone: "map shadows to the first color and highlights to the second, by luminance",
+    monochrome: "single-hue rendering in the given color (RRGGBB)",
+    pixelate: "mosaic into blocks of the given pixel size, each block averaged",
+    flip: "mirror the image: `h` horizontal, `v` vertical",
+    blur_region: "gaussian-blur the rectangle (x,y,w,h) in pixels at this point in the chain (redaction)",
+    overlay: "composite another image over the result: (url,x,y,alpha,blend[,width %]) with blend normal, multiply, screen, or overlay",
+    pixelate_region: "pixelate the rectangle (x,y,w,h) in pixels at this point in the chain (redaction)",
+};
+const MAX_DIMENSION = 16383;
+function parseDimension(part) {
+    let flip = false;
+    let digits = part;
+    if (digits.startsWith("-")) {
+        flip = true;
+        digits = digits.slice(1);
+    }
+    if (digits === "" || digits === "0")
+        return { kind: "proportional", value: 0, flip };
+    if (digits === "orig")
+        return { kind: "original", value: 0, flip };
+    if (!/^\+?\d+$/.test(digits))
+        return null;
+    if (BigInt(digits) > BigInt(MAX_DIMENSION))
+        return null;
+    return { kind: "pixels", value: Number(digits), flip };
+}
+function parseSizeSegment(seg) {
+    const x = seg.indexOf("x");
+    if (x === -1)
+        return null;
+    const w = parseDimension(seg.slice(0, x));
+    const h = parseDimension(seg.slice(x + 1));
+    if (!w || !h)
+        return null;
+    return { w, h };
+}
+function isExactBox(size) {
+    const px = (d) => d.kind === "pixels" && d.value >= 1 && !d.flip;
+    return px(size.w) && px(size.h);
+}
+function sizeBlurb(seg) {
+    const size = parseSizeSegment(seg);
+    if (!size)
+        return `resize per ${seg}`;
+    const describe = (d, axis) => d.kind === "original"
+        ? `the original ${axis}`
+        : d.kind === "proportional"
+            ? `proportional ${axis}`
+            : `${d.value}px ${axis}`;
+    const flips = [
+        size.w.flip ? "flipped horizontally" : null,
+        size.h.flip ? "flipped vertically" : null,
+    ].filter(Boolean);
+    return `resize to ${describe(size.w, "width")} by ${describe(size.h, "height")}${flips.length ? ` (${flips.join(", ")})` : ""}`;
+}
+const NO_ARG_FILTERS = new Set([
+    "grayscale",
+    "invert",
+    "no_upscale",
+    "equalize",
+    "removebg",
+    "keep_profile",
+    "sepia",
+    "blurfaces",
+    "pixelatefaces",
+]);
+const FORMAT_NAMES = new Set(["jpeg", "jpg", "png", "webp", "jxl", "avif", "gif", "mp4", "webm"]);
+const ANCHOR_NAMES = new Set([
+    "top-left",
+    "top-center",
+    "top-right",
+    "center-left",
+    "center",
+    "center-right",
+    "bottom-left",
+    "bottom-center",
+    "bottom-right",
+]);
+function isIntIn(s, min, max) {
+    // Rust's integer from_str syntax: an optional sign (the
+    // unsigned parsers accept '+' too), then digits.
+    return /^[+-]?\d+$/.test(s) && BigInt(s) >= BigInt(min) && BigInt(s) <= BigInt(max);
+}
+const RUST_FLOAT = /^[+-]?(\d+\.?\d*|\.\d+)([eE][+-]?\d+)?$/;
+function isFloat(s) {
+    // Rust's f32::from_str syntax (AP-23): plain decimal with
+    // an optional exponent; no hex, no surrounding whitespace,
+    // both of which Number() would otherwise accept. The
+    // inf/nan spellings Rust also parses are non-finite, and
+    // every caller rejects non-finite values, so the verdicts
+    // agree without them.
+    return RUST_FLOAT.test(s) && Number.isFinite(Number(s));
+}
+const KERNEL_VALUE = /^-?\d+(\.\d+)?$/;
+function isKernelValue(s) {
+    // The server's kernel-value grammar (url.rs
+    // parse_kernel_value): the rotate angle's strict decimal
+    // form, no exponent and no leading dot, bounded to 1024
+    // in absolute value.
+    return KERNEL_VALUE.test(s) && Math.abs(Number(s)) <= 1024;
+}
+function percentDecodable(s) {
+    try {
+        return decodeURIComponent(s);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Validate one filter against the server's rules (url.rs
+ * parse_filters, ported). `args` is null when the filter has
+ * no parentheses (empty parens count as none, like the
+ * server) and the raw argument string otherwise. Returns an
+ * error string, or null when the server would accept it.
+ */
+function validateFilter(name, args) {
+    const bad = `the server rejects this filter: ${name}${args === null ? "" : `(${args})`}`;
+    if (NO_ARG_FILTERS.has(name)) {
+        return args === null ? null : bad;
+    }
+    switch (name) {
+        case "trim":
+            return args === null || isIntIn(args, 0, 255) ? null : bad;
+        case "blur":
+        case "sharpen":
+            return args !== null && isFloat(args) && Number(args) > 0 ? null : bad;
+        case "brighten":
+            return args !== null && isIntIn(args, -255, 255) ? null : bad;
+        case "huerotate":
+            return args !== null && isIntIn(args, -2147483648, 2147483647) ? null : bad;
+        case "contrast":
+            return args !== null && isFloat(args) && Number(args) >= -100 && Number(args) <= 100
+                ? null
+                : bad;
+        case "saturation":
+            return args !== null && isFloat(args) && Number(args) >= 0 && Number(args) <= 255
+                ? null
+                : bad;
+        case "quality":
+            return args === "auto" || (args !== null && isIntIn(args, 1, 100)) ? null : bad;
+        case "format":
+            return args !== null && FORMAT_NAMES.has(args) ? null : bad;
+        case "rgb": {
+            if (args === null)
+                return bad;
+            const parts = args.split(",");
+            return parts.length === 3 && parts.every((p) => isIntIn(p, -255, 255)) ? null : bad;
+        }
+        case "curve": {
+            if (args === null)
+                return bad;
+            const parts = args.split(",");
+            if (!["rgb", "r", "g", "b"].includes(parts[0]))
+                return bad;
+            const coords = parts.slice(1);
+            if (coords.length < 4 || coords.length > 32 || coords.length % 2 !== 0)
+                return bad;
+            if (!coords.every((p) => isIntIn(p, 0, 255)))
+                return bad;
+            for (let i = 2; i < coords.length; i += 2) {
+                if (Number(coords[i]) <= Number(coords[i - 2]))
+                    return bad;
+            }
+            return null;
+        }
+        case "convolution": {
+            if (args === null)
+                return bad;
+            const parts = args.split(",");
+            if (parts.length !== 10 && parts.length !== 26)
+                return bad;
+            const flag = parts[parts.length - 1];
+            if (flag !== "0" && flag !== "1")
+                return bad;
+            return parts.slice(0, -1).every((p) => isKernelValue(p)) ? null : bad;
+        }
+        case "noise":
+            return args !== null && isIntIn(args, 0, 100) ? null : bad;
+        case "facepad":
+            return args !== null && isFloat(args) && Number(args) >= 0 && Number(args) <= 3
+                ? null
+                : bad;
+        case "upscale":
+            return args !== null && /^[+-]?\d+$/.test(args) && (Number(args) === 2 || Number(args) === 4)
+                ? null
+                : bad;
+        case "dpr":
+            return args !== null && isFloat(args) && [1, 1.5, 2, 3].includes(Number(args))
+                ? null
+                : bad;
+        case "rotate":
+            return args !== null && /^-?\d+(\.\d+)?$/.test(args) && Math.abs(Number(args)) <= 36000
+                ? null
+                : bad;
+        case "fill":
+            return args !== null && /^[0-9a-fA-F]{6}$/.test(args) ? null : bad;
+        case "radius": {
+            if (args === null)
+                return bad;
+            const parts = args.split(",");
+            return (parts.length === 1 || parts.length === 4) &&
+                parts.every((p) => isIntIn(p, 0, 16383))
+                ? null
+                : bad;
+        }
+        case "border": {
+            if (args === null)
+                return bad;
+            const parts = args.split(",");
+            return parts.length === 2 &&
+                isIntIn(parts[0], 1, 16383) &&
+                /^[0-9a-fA-F]{6}$/.test(parts[1])
+                ? null
+                : bad;
+        }
+        case "mask":
+            return args === "circle" || args === "ellipse" ? null : bad;
+        case "duotone": {
+            if (args === null)
+                return bad;
+            const parts = args.split(",");
+            return parts.length === 2 && parts.every((p) => /^[0-9a-fA-F]{6}$/.test(p)) ? null : bad;
+        }
+        case "monochrome":
+            return args !== null && /^[0-9a-fA-F]{6}$/.test(args) ? null : bad;
+        case "pixelate":
+            return args !== null && isIntIn(args, 1, 16383) ? null : bad;
+        case "flip":
+            return args === "h" || args === "v" ? null : bad;
+        case "overlay": {
+            if (args === null)
+                return bad;
+            // The server splits from the right (rsplitn(6, ',')):
+            // with six or more fields the rightmost IS the width
+            // and must parse, and the URL keeps any commas left
+            // over. Splitting any other way misreads both.
+            const fields = args.split(",");
+            if (fields.length < 5)
+                return bad;
+            let rest = fields;
+            if (fields.length >= 6) {
+                if (!isIntIn(fields[fields.length - 1], 1, 400))
+                    return bad;
+                rest = fields.slice(0, -1);
+            }
+            const blend = rest[rest.length - 1];
+            if (!["normal", "multiply", "screen", "overlay"].includes(blend))
+                return bad;
+            if (!isIntIn(rest[rest.length - 2], 0, 100))
+                return bad;
+            if (!isIntIn(rest[rest.length - 3], -2147483648, 2147483647))
+                return bad;
+            if (!isIntIn(rest[rest.length - 4], -2147483648, 2147483647))
+                return bad;
+            const url = percentDecodable(rest.slice(0, -4).join(","));
+            return url !== null && url !== "" ? null : bad;
+        }
+        case "blurclass":
+        case "pixelateclass": {
+            if (args === null)
+                return bad;
+            const decoded = percentDecodable(args);
+            if (decoded === null)
+                return bad;
+            const name = decoded.trim();
+            return name.length >= 1 &&
+                new TextEncoder().encode(name).length <= 64 &&
+                /^[\p{L}\p{N} _.\-/]+$/u.test(name)
+                ? null
+                : bad;
+        }
+        case "blur_region":
+        case "pixelate_region": {
+            if (args === null)
+                return bad;
+            const parts = args.split(",");
+            return parts.length === 4 &&
+                parts.every((p) => isIntIn(p, 0, 16383)) &&
+                Number(parts[2]) >= 1 &&
+                Number(parts[3]) >= 1
+                ? null
+                : bad;
+        }
+        case "max_bytes":
+            return args !== null &&
+                /^[+-]?\d+$/.test(args) &&
+                BigInt(args) >= 1n &&
+                BigInt(args) <= 18446744073709551615n
+                ? null
+                : bad;
+        case "text": {
+            if (args === null)
+                return bad;
+            const parts = args.split(",");
+            if (parts.length < 4)
+                return bad;
+            const anchor = parts[parts.length - 1];
+            const color = parts[parts.length - 2];
+            const size = parts[parts.length - 3];
+            const text = percentDecodable(parts.slice(0, -3).join(","));
+            return ANCHOR_NAMES.has(anchor) &&
+                /^[0-9a-fA-F]{6}([0-9a-fA-F]{2})?$/.test(color) &&
+                isIntIn(size, 1, 1000) &&
+                text !== null &&
+                text !== ""
+                ? null
+                : bad;
+        }
+        case "watermark": {
+            if (args === null)
+                return bad;
+            const parts = args.split(",");
+            if (parts.length < 4)
+                return bad;
+            const alpha = parts[parts.length - 1];
+            const y = parts[parts.length - 2];
+            const x = parts[parts.length - 3];
+            const url = percentDecodable(parts.slice(0, -3).join(","));
+            return isIntIn(alpha, 0, 100) &&
+                isIntIn(y, -2147483648, 2147483647) &&
+                isIntIn(x, -2147483648, 2147483647) &&
+                url !== null &&
+                url !== ""
+                ? null
+                : bad;
+        }
+        default:
+            return `unknown filter: ${name}`;
+    }
+}
+function explainFilters(rest) {
+    // The server splits the list naively on ':'; a ':' inside
+    // parentheses is not special there either.
+    const parts = rest.split(":");
+    const blurbs = [];
+    for (const part of parts) {
+        const match = part.match(/^([a-z_0-9]+)(?:\((.*)\))?$/);
+        if (!match) {
+            return { error: `malformed filter: ${part}` };
+        }
+        const [, name, rawArgs] = match;
+        const args = rawArgs === undefined || rawArgs === "" ? null : rawArgs;
+        const blurb = FILTER_DESCRIPTIONS[name];
+        if (!blurb) {
+            return { error: `unknown filter: ${name}` };
+        }
+        const invalid = validateFilter(name, args);
+        if (invalid) {
+            return { error: invalid };
+        }
+        blurbs.push(args !== null ? `${name}(${args}): ${blurb}` : `${name}: ${blurb}`);
+    }
+    return { detail: blurbs.join("; ") };
+}
+const ALIGN_NAMES = new Set(["center", "smart", "face", "top", "bottom", "left", "right", "top-left", "top-right", "bottom-left", "bottom-right"]);
+const U64_MAX = 18446744073709551615n;
+function explainSegment(seg, nowSeconds) {
+    if (seg.startsWith("exp:")) {
+        const value = seg.slice(4);
+        if (!/^\d+$/.test(value)) {
+            return { kind: "expiry", title: "Expiry", error: `malformed expiry: ${seg}` };
+        }
+        // Parse as BigInt: the server reads a u64, and a huge
+        // value must report its clean 400, not crash the date
+        // arithmetic (audit P-3).
+        const seconds = BigInt(value);
+        if (seconds > U64_MAX) {
+            return {
+                kind: "expiry",
+                title: "Expiry",
+                error: `expiry overflows the server's u64 parser: ${seg} (the server answers 400)`,
+            };
+        }
+        const expired = BigInt(nowSeconds) >= seconds;
+        const asNumber = Number(seconds);
+        const when = asNumber <= 8640000000000
+            ? new Date(asNumber * 1000).toISOString().replace("T", " ").replace(".000Z", " UTC")
+            : "a date beyond representation";
+        return {
+            kind: "expiry",
+            title: "Expiry",
+            detail: `valid strictly before ${when} (${value})${expired ? " — EXPIRED at the reference time" : ""}`,
+            expired,
+        };
+    }
+    if (seg.startsWith("maxage:")) {
+        const value = seg.slice(7);
+        if (!/^\d+$/.test(value)) {
+            return {
+                kind: "maxage",
+                title: "Max-age",
+                error: `malformed maxage: ${seg} (want maxage:<seconds> from 0 to 31536000)`,
+            };
+        }
+        if (BigInt(value) > 31536000n) {
+            return {
+                kind: "maxage",
+                title: "Max-age",
+                error: `maxage out of range: ${seg} (0 to 31536000 seconds; the server answers 400)`,
+            };
+        }
+        return {
+            kind: "maxage",
+            title: "Max-age",
+            detail: value === "0"
+                ? "this response is served with Cache-Control: public, max-age=0 and no immutable flag: caches must revalidate before reuse; the stored image is unchanged"
+                : `this response is served with Cache-Control max-age ${value} seconds instead of the default year; the stored image is unchanged`,
+        };
+    }
+    if (seg.startsWith("debug:")) {
+        const value = seg.slice(6);
+        if (value !== "focal") {
+            return {
+                kind: "debug",
+                title: "Debug view",
+                error: `unsupported debug view: ${seg} (want debug:focal; the server answers 400)`,
+            };
+        }
+        return {
+            kind: "debug",
+            title: "Debug view",
+            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, detected face boxes (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",
+        };
+    }
+    if (seg.startsWith("preset:")) {
+        const name = seg.slice(7);
+        if (!name) {
+            return { kind: "preset", title: "Preset", error: "empty preset name" };
+        }
+        return {
+            kind: "preset",
+            title: "Preset",
+            detail: `expands server-side to the operations the operator named "${name}"; the signature covers this reference, not the expansion`,
+        };
+    }
+    if (seg.startsWith("crop-rect:")) {
+        const rest = seg.slice(10);
+        const m = rest.match(/^([+-]?\d+)x([+-]?\d+):([+-]?\d+)x([+-]?\d+)$/);
+        if (!m ||
+            m.slice(1).some((n) => BigInt(n) < 0n || BigInt(n) > 4294967295n) ||
+            BigInt(m[3]) <= BigInt(m[1]) ||
+            BigInt(m[4]) <= BigInt(m[2])) {
+            return {
+                kind: "operation",
+                title: "Crop rectangle",
+                error: `malformed crop-rect segment: ${seg} (want crop-rect:<l>x<t>:<r>x<b> with right > left and bottom > top)`,
+            };
+        }
+        return { kind: "operation", title: "Crop rectangle", detail: `crop the exact rectangle ${rest} (left x top : right x bottom)` };
+    }
+    if (seg.startsWith("focal:")) {
+        const rest = seg.slice(6);
+        const m = rest.match(/^([+-]?\d+)x([+-]?\d+):([+-]?\d+)x([+-]?\d+)$/);
+        if (!m ||
+            m.slice(1).some((n) => BigInt(n) < 0n || BigInt(n) > 4294967295n) ||
+            BigInt(m[3]) <= BigInt(m[1]) ||
+            BigInt(m[4]) <= BigInt(m[2])) {
+            return {
+                kind: "operation",
+                title: "Focal rectangle",
+                error: `malformed focal segment: ${seg} (want focal:<l>x<t>:<r>x<b> with right > left and bottom > top)`,
+            };
+        }
+        return { kind: "operation", title: "Focal rectangle", detail: `set the focal rectangle ${rest} for the next crop (left x top : right x bottom)` };
+    }
+    if (seg.startsWith("crop:")) {
+        const rest = seg.slice(5);
+        const idx = rest.indexOf(":");
+        const dims = idx === -1 ? rest : rest.slice(0, idx);
+        const align = idx === -1 ? "center" : rest.slice(idx + 1);
+        const cropSize = parseSizeSegment(dims);
+        if (!cropSize || !isExactBox(cropSize) || !ALIGN_NAMES.has(align)) {
+            return {
+                kind: "operation",
+                title: "Crop",
+                error: `malformed crop segment: ${seg} (want crop:<w>x<h>[:center|smart|face|top|bottom|left|right|top-left|top-right|bottom-left|bottom-right], pixels only, no flips)`,
+            };
+        }
+        return { kind: "operation", title: "Crop", detail: `crop to the aspect of ${dims} and resize to it; alignment: ${align === "center" ? "center (or the focal point for smart)" : align}` };
+    }
+    if (seg.startsWith("fit-in:")) {
+        const rest = seg.slice(7);
+        const idx = rest.indexOf(":");
+        const dims = idx === -1 ? rest : rest.slice(0, idx);
+        const modifier = idx === -1 ? null : rest.slice(idx + 1);
+        const size = parseSizeSegment(dims);
+        if (!size || size.w.flip || size.h.flip || (modifier !== null && modifier !== "adaptive")) {
+            return { kind: "operation", title: "Fit in", error: `malformed fit-in segment: ${seg} (want fit-in:<w>x<h>[:adaptive], flips are not allowed here)` };
+        }
+        if (modifier === "adaptive") {
+            return { kind: "operation", title: "Fit inside a box", detail: `scale proportionally to fit inside ${dims}, swapping the box axes when the source orientation disagrees (adaptive)` };
+        }
+        return { kind: "operation", title: "Fit inside a box", detail: `scale proportionally to fit inside ${rest}` };
+    }
+    if (seg.startsWith("pad:")) {
+        const rest = seg.slice(4);
+        const idx = rest.indexOf(":");
+        const dims = idx === -1 ? rest : rest.slice(0, idx);
+        const fill = idx === -1 ? null : rest.slice(idx + 1);
+        const padSize = parseSizeSegment(dims);
+        if (!padSize || !isExactBox(padSize) || (fill !== null && fill !== "blur" && !/^[0-9a-fA-F]{6}$/.test(fill))) {
+            return { kind: "operation", title: "Pad", error: `malformed pad segment: ${seg} (want pad:<w>x<h>[:<hex>|blur], pixels only, no flips)` };
+        }
+        return { kind: "operation", title: "Pad", detail: `fit inside ${dims} and fill the canvas to exactly that size, fill: ${fill ?? "the fill(...) color or black"}` };
+    }
+    if (seg.startsWith("filters:")) {
+        const { detail, error } = explainFilters(seg.slice(8));
+        if (error) {
+            return { kind: "operation", title: "Filters", error };
+        }
+        return { kind: "operation", title: "Filters", detail };
+    }
+    if (parseSizeSegment(seg)) {
+        return { kind: "operation", title: "Resize", detail: sizeBlurb(seg) };
+    }
+    return null; // Not an operation: the source starts here.
+}
+/**
+ * Parse a crabcrop URL (or bare path) back into its pieces,
+ * explaining each segment. Mirrors the server's dispatch:
+ * segments are operations until the first segment that is not
+ * one; everything from there is the source.
+ *
+ * Returns { signature, segments, source, remainder, errors }
+ * where segments carry { raw, kind, title, detail?, error? }.
+ */
+export function explainUrl(input, nowSeconds = Math.floor(Date.now() / 1000)) {
+    // Extract the path by string surgery, never via the URL
+    // parser: WHATWG parsing resolves dot segments (.. and
+    // %2e%2e) that the server treats as literal path bytes
+    // (audit P-3). A query or fragment is not part of the
+    // signed path, on either side.
+    let path = input.trim();
+    const scheme = path.indexOf("://");
+    if (scheme > 0 && /^[a-zA-Z][a-zA-Z0-9+.-]*$/.test(path.slice(0, scheme))) {
+        const afterAuthority = path.slice(scheme + 3);
+        const slash = afterAuthority.indexOf("/");
+        path = slash === -1 ? "" : afterAuthority.slice(slash + 1);
+    }
+    else if (path.startsWith("/")) {
+        path = path.slice(1);
+    }
+    const cut = path.search(/[?#]/);
+    if (cut !== -1) {
+        path = path.slice(0, cut);
+    }
+    const errors = [];
+    const slash = path.indexOf("/");
+    if (slash === -1) {
+        return { signature: null, segments: [], source: "", remainder: "", errors: ["no signature segment: the path is a single segment"] };
+    }
+    const signatureRaw = path.slice(0, slash);
+    const remainder = path.slice(slash + 1);
+    let signature;
+    const keyed = signatureRaw.match(/^([A-Za-z0-9_-]{1,32}):([0-9a-f]{64})$/);
+    if (signatureRaw === "unsafe") {
+        signature = { kind: "unsafe", value: signatureRaw, detail: "unsigned; the server honors it only with CRABCROP_ALLOW_UNSAFE or in presets-only deployments" };
+    }
+    else if (keyed) {
+        signature = { kind: "hmac", value: keyed[2], keyId: keyed[1], detail: `HMAC-SHA256 of the remainder, signed with key "${keyed[1]}"; the server verifies it against that key only (secret rotation)` };
+    }
+    else if (/^[0-9a-f]{64}$/.test(signatureRaw)) {
+        signature = { kind: "hmac", value: signatureRaw, detail: "HMAC-SHA256 of the remainder; paste the secret to verify it below" };
+    }
+    else if (/^[0-9a-f]+$/.test(signatureRaw)) {
+        signature = { kind: "invalid", value: signatureRaw, detail: "lowercase hex, but not a full 64-character HMAC tag: the server will answer 403" };
+        errors.push("malformed signature segment");
+    }
+    else {
+        signature = { kind: "invalid", value: signatureRaw, detail: "not `unsafe` and not lowercase hex: the server rejects it as malformed (400)" };
+        errors.push("malformed signature segment");
+    }
+    const segments = [];
+    let rest = remainder;
+    let source = "";
+    for (;;) {
+        const idx = rest.indexOf("/");
+        const seg = idx === -1 ? rest : rest.slice(0, idx);
+        if (seg === "" && idx !== -1) {
+            // An empty segment in the operations run (a doubled
+            // slash): the server answers 400 (missing source URL)
+            // instead of treating the rest as a source with a
+            // leading slash (AP-23).
+            const error = "empty segment in the path: the server answers 400 (missing source URL)";
+            segments.push({ raw: seg, kind: "operation", title: "Empty segment", error });
+            errors.push(error);
+            rest = rest.slice(idx + 1);
+            continue;
+        }
+        const explained = seg === "" ? null : explainSegment(seg, nowSeconds);
+        if (!explained) {
+            source = rest;
+            break;
+        }
+        segments.push({ raw: seg, ...explained });
+        if (explained.error) {
+            errors.push(explained.error);
+        }
+        if (idx === -1) {
+            errors.push("the URL ends after the operations: no source");
+            rest = "";
+            break;
+        }
+        rest = rest.slice(idx + 1);
+    }
+    if (!source && rest) {
+        source = rest;
+    }
+    return { signature, segments, source, remainder, errors };
+}