From 7f8b47fc0ace3ce2fbbce2cb3a90439ae046ca91 Mon Sep 17 00:00:00 2001
From: Nick the Sick <computers@nickthesick.com>
Date: Sun, 8 Mar 2026 18:55:01 +0100
Subject: [PATCH] fix: VArg fallback for non-JSON values and handler sort
 comparator
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

VArg silently returned undefined for values that fail JSON.parse() —
for example, hex colour strings with a leading zero like "030712" are
invalid JSON numbers and throw. The catch block swallowed the error,
returning undefined, which then became the string "undefined" via
String(undefined) in background.apply, ultimately passed to sharp as a
background colour and causing: "Unable to parse color from string: undefined".

Fix: return the raw argument string as a fallback when JSON parsing fails.

The handler sort comparator also had a bug: it stringified the numeric
order field (-1) and compared it with localeCompare against modifier
names. Whether punctuation/symbols sort before or after letters is
locale-dependent, so order: -1 modifiers (background, fit, position,
quality) were not reliably applied first. Fix: compare numerically with
a name-based fallback for equal-order handlers.

Also removes the stale "TODO: Support background" comment from flatten,
and collapses single-property object literals to one line for consistency.
---
 src/handlers/handlers.ts | 9 ++-------
 src/handlers/utils.ts    | 1 +
 src/ipx.ts               | 9 ++++++---
 3 files changed, 9 insertions(+), 10 deletions(-)

diff --git a/src/handlers/handlers.ts b/src/handlers/handlers.ts
index 0c19dc3..0f65d56 100644
--- a/src/handlers/handlers.ts
+++ b/src/handlers/handlers.ts
@@ -149,9 +149,7 @@ export const extract: Handler = {
 export const rotate: Handler = {
   args: [VArg],
   apply: (context, pipe, angel) => {
-    return pipe.rotate(angel, {
-      background: context.background,
-    });
+    return pipe.rotate(angel, { background: context.background });
   },
 };
 
@@ -196,13 +194,10 @@ export const blur: Handler = {
 };
 
 // https://sharp.pixelplumbing.com/api-operation#flatten
-// TODO: Support background
 export const flatten: Handler = {
   args: [VArg, VArg, VArg],
   apply: (context, pipe) => {
-    return pipe.flatten({
-      background: context.background,
-    });
+    return pipe.flatten({ background: context.background });
   },
 };
 
diff --git a/src/handlers/utils.ts b/src/handlers/utils.ts
index 7b53af8..574c715 100644
--- a/src/handlers/utils.ts
+++ b/src/handlers/utils.ts
@@ -16,6 +16,7 @@ export function VArg(argument: string) {
   } catch {
     // ignore parsing errors
   }
+  return argument;
 }
 
 export function parseArgs(
diff --git a/src/ipx.ts b/src/ipx.ts
index 9e7b6a3..d6f3372 100644
--- a/src/ipx.ts
+++ b/src/ipx.ts
@@ -345,9 +345,12 @@ export function createIPX(userOptions: IPXOptions): IPX {
         }))
         .filter((h) => h.handler)
         .sort((a, b) => {
-          const aKey = (a.handler.order || a.name || "").toString();
-          const bKey = (b.handler.order || b.name || "").toString();
-          return aKey.localeCompare(bKey);
+          const aOrder =
+            typeof a.handler.order === "number" ? a.handler.order : Infinity;
+          const bOrder =
+            typeof b.handler.order === "number" ? b.handler.order : Infinity;
+          if (aOrder !== bOrder) return aOrder - bOrder;
+          return (a.name || "").localeCompare(b.name || "");
         });
 
       // Apply handlers