fix(units)!: prefer input-family unit for non-integer scaled values

BREAKING CHANGE: `scaleBy` and `scaleTo` now emit `FractionValue`
instead of `DecimalValue` for scaled quantities whose result can be
expressed as an allowed fraction on a fraction-enabled unit (e.g. 0.5
on `cup` → `{type:"fraction", num:1, den:2}`). This affects units that
have `fractions.enabled` set (cup, lb, oz, tsp, tbsp, fl-oz, etc.).
Units without fraction support (g, ml, kg, l, piece, …) are unaffected.
Callers that branch on `value.type` or access `value.decimal` directly
for these units must handle `FractionValue` alongside `DecimalValue`.

Author: tmlmt

src/quantities/mutations.ts

@@ -703,13 +703,21 @@ export function applyBestUnit(
 
   // Get canonical name of the original unit for comparison
   const originalCanonicalName = normalizeUnit(extended.unit.name)?.name;
-
-  // If same unit (by canonical name match), no change needed - preserve original unit name
-  if (bestUnit.name === originalCanonicalName) {
-    return q;
-  }
-
-  // Format the value for the best unit
+  const isSameUnit = bestUnit.name === originalCanonicalName;
+
+  // Determine the output unit representation:
+  // - When upgrading/downgrading to a different unit, use the canonical best-unit name.
+  // - When keeping the same unit, preserve the original alias (e.g. "cups" stays "cups").
+  const outputUnit = isSameUnit
+    ? q.unit
+    : typeof q.unit === "string"
+      ? bestUnit.name
+      : { name: bestUnit.name };
+
+  // Format the value for the best unit (applies fraction representation when the unit supports
+  // it, e.g. 0.5 cup → {type:"fraction", num:1, den:2}).
+  // This is done even when the unit hasn't changed, because the scaling factor may have
+  // produced a decimal that can now be expressed as a nicer fraction (e.g. 0.5 → 1/2).
   const formattedValue = formatOutputValue(bestValue, bestUnit);
 
   // Handle ranges: scale to the best unit
@@ -726,8 +734,7 @@ export function applyBestUnit(
         min: formatOutputValue(minValue, bestUnit),
         max: formatOutputValue(maxValue, bestUnit),
       },
-      unit:
-        typeof q.unit === "string" ? bestUnit.name : { name: bestUnit.name },
+      unit: outputUnit,
     } as QuantityWithExtendedUnit | QuantityWithPlainUnit;
   }
 
@@ -737,7 +744,7 @@ export function applyBestUnit(
       type: "fixed",
       value: formattedValue,
     },
-    unit: typeof q.unit === "string" ? bestUnit.name : { name: bestUnit.name },
+    unit: outputUnit,
   } as QuantityWithExtendedUnit | QuantityWithPlainUnit;
 }
 

src/units/conversion.ts

@@ -122,22 +122,28 @@ export function findBestUnit(
       return integersInInputFamily.sort((a, b) => a.value - b.value)[0]!;
     }
 
-    // Second priority: integers in any family (prefer system-appropriate units)
+    // Second priority: non-integers in input family (prefer keeping user's unit even if fractional).
+    // !isCloseToInteger is implicit here: any input-family integer would have been caught by
+    // priority 1 above, so the candidates reaching here are guaranteed non-integer.
+    // Sorted descending by value so we pick the largest (most natural) fraction.
+    const nonIntegersInInputFamily = inRange.filter((c) =>
+      inputUnitNames.has(c.unit.name),
+    );
+    if (nonIntegersInInputFamily.length > 0) {
+      return nonIntegersInInputFamily.sort((a, b) => b.value - a.value)[0]!;
+    }
+
+    // Third priority: integers in any family (prefer system-appropriate units)
     const integersAny = inRange.filter((c) => isCloseToInteger(c.value));
     if (integersAny.length > 0) {
       // Sort by value
       return integersAny.sort((a, b) => a.value - b.value)[0]!;
     }
 
-    // Third priority: smallest value in range (prioritizing input family)
-    return inRange.sort((a, b) => {
-      // Prioritize input family
-      const aInFamily = inputUnitNames.has(a.unit.name) ? 0 : 1;
-      const bInFamily = inputUnitNames.has(b.unit.name) ? 0 : 1;
-      if (aInFamily !== bInFamily) return aInFamily - bInFamily;
-      // Then by smallest value
-      return a.value - b.value;
-    })[0]!;
+    // Fourth priority: smallest non-integer value in range
+    // At this point, all inRange candidates are guaranteed to be non-input-family (since any
+    // input-family unit in range would have been caught by priority 1 or 2 above).
+    return inRange.sort((a, b) => a.value - b.value)[0]!;
   }
 
   return candidatesWithValues.sort((a, b) => {

test/quantities_mutations.test.ts

@@ -1371,8 +1371,12 @@ describe("applyBestUnit", () => {
       unit: { name: "mL" },
     };
     const result = applyBestUnit(q);
-    expect(result).toBe(q);
+    // Same unit; value is a whole number so stays decimal (mL has no fractions)
     expect(result.unit?.name).toBe("mL");
+    expect(result.quantity).toEqual({
+      type: "fixed",
+      value: { type: "decimal", decimal: 100 },
+    });
   });
 
   it("should preserve unit alias when best unit is the same (cups stays cups)", () => {
@@ -1381,8 +1385,12 @@ describe("applyBestUnit", () => {
       unit: { name: "cups" },
     };
     const result = applyBestUnit(q);
-    expect(result).toBe(q);
+    // Same unit; 2 is a whole number so stays decimal
     expect(result.unit?.name).toBe("cups");
+    expect(result.quantity).toEqual({
+      type: "fixed",
+      value: { type: "decimal", decimal: 2 },
+    });
   });
 
   it("should infer metric system from unit when system not provided", () => {
@@ -1455,6 +1463,25 @@ describe("applyBestUnit", () => {
       max: { type: "decimal", decimal: 1.5 },
     });
   });
+
+  it("should apply fraction formatting to range values when unit stays the same", () => {
+    // 0.5-1 cup stays as cup but min should become fraction 1/2
+    const q: QuantityWithExtendedUnit = {
+      quantity: {
+        type: "range",
+        min: { type: "decimal", decimal: 0.5 },
+        max: { type: "decimal", decimal: 1 },
+      },
+      unit: { name: "cup" },
+    };
+    const result = applyBestUnit(q);
+    expect(result.unit).toEqual({ name: "cup" });
+    expect(result.quantity).toEqual({
+      type: "range",
+      min: { type: "fraction", num: 1, den: 2 },
+      max: { type: "decimal", decimal: 1 },
+    });
+  });
 });
 
 describe("subtractQuantities", () => {

test/recipe_scaling.test.ts

@@ -850,4 +850,78 @@ Add @eggs{5%piece}.
       unit: { name: "piece" },
     });
   });
+
+  it("should keep 1/2 cup after round-trip scale ×2 then ×0.5 (not convert to 4 fl-oz)", () => {
+    // @cream{1/2%cup} → ×2 = 1 cup ✓ → ×0.5 should return to 1/2 cup, NOT 4 fl-oz
+    const recipe = new Recipe(`
+---
+servings: 1
+---
+Add @cream{1/2%cup}.
+    `);
+    const step = (r: Recipe) =>
+      (r.sections[0]!.content[0]! as Step).items.find(
+        (i) => i.type === "ingredient",
+      ) as IngredientItem;
+
+    const doubled = recipe.scaleBy(2);
+    expect(step(doubled).alternatives[0]).toMatchObject({
+      quantity: { type: "fixed", value: { type: "decimal", decimal: 1 } },
+      unit: { name: "cup" },
+    });
+
+    const roundTrip = doubled.scaleBy(0.5);
+    // 0.5 cup is an allowed fraction (1/2), so it's returned as FractionValue
+    expect(step(roundTrip).alternatives[0]).toMatchObject({
+      quantity: { type: "fixed", value: { type: "fraction", num: 1, den: 2 } },
+      unit: { name: "cup" },
+    });
+  });
+
+  it("should keep 1/2 lb after round-trip scale ×2 then ×0.5 (not convert to 8 oz)", () => {
+    const recipe = new Recipe(`
+---
+servings: 1
+---
+Add @butter{1/2%lb}.
+    `);
+    const step = (r: Recipe) =>
+      (r.sections[0]!.content[0]! as Step).items.find(
+        (i) => i.type === "ingredient",
+      ) as IngredientItem;
+
+    const doubled = recipe.scaleBy(2);
+    expect(step(doubled).alternatives[0]).toMatchObject({
+      quantity: { type: "fixed", value: { type: "decimal", decimal: 1 } },
+      unit: { name: "lb" },
+    });
+
+    const roundTrip = doubled.scaleBy(0.5);
+    // 0.5 lb is an allowed fraction (1/2), so it's returned as FractionValue
+    expect(step(roundTrip).alternatives[0]).toMatchObject({
+      quantity: { type: "fixed", value: { type: "fraction", num: 1, den: 2 } },
+      unit: { name: "lb" },
+    });
+  });
+
+  it("should keep 1.5 cups as cups rather than converting to 12 fl-oz", () => {
+    // 1 cup × 1.5 = 1.5 cups: non-integer in input family should beat integer in another family
+    const recipe = new Recipe(`
+---
+servings: 2
+---
+Add @cream{1%cup}.
+    `);
+    const step = (r: Recipe) =>
+      (r.sections[0]!.content[0]! as Step).items.find(
+        (i) => i.type === "ingredient",
+      ) as IngredientItem;
+
+    const scaled = recipe.scaleTo(3); // 1 cup for 2 servings → 1.5 cups for 3 servings
+    // 1.5 cup = 3/2, which is an allowed fraction of cup, so it's returned as FractionValue
+    expect(step(scaled).alternatives[0]).toMatchObject({
+      quantity: { type: "fixed", value: { type: "fraction", num: 3, den: 2 } },
+      unit: { name: "cup" },
+    });
+  });
 });

test/units_conversion.test.ts

@@ -58,8 +58,9 @@ describe("findBestUnit", () => {
     expect(result.value).toBe(240);
   });
 
-  it("should prefer the smallest integer of all integers in any family over non-integers in input family", () => {
-    // 236.6 ml = ~1 cup or ~8 fl-oz
+  it("should prefer the smallest integer of all integers in any family over non-integers in input family (when input family unit has no fractions)", () => {
+    // 236.6 ml in US system: mL is metric (not US-compatible), so excluded from candidates.
+    // cup ≈ 1 (integer, any family) wins. This is the system-conversion case.
     const mLDef = normalizeUnit("mL")!;
     const result = findBestUnit(236.6, "volume", "US", [mLDef]);
     expect(result.unit.name).toBe("cup");
@@ -136,4 +137,44 @@ describe("findBestUnit", () => {
     expect(result.unit.name).toBe("tsp");
     expect(result.value).toBeCloseTo(0.06, 2);
   });
+
+  it("should prefer non-integer value in input family over integer in another family (Option B)", () => {
+    // 118.294 ml = 0.5 cup (fraction, input family) vs 4 fl-oz (integer, other family)
+    // Priority 2: non-integer in input family wins → cup
+    const cupDef = normalizeUnit("cup")!;
+    const result = findBestUnit(118.294, "volume", "US", [cupDef]);
+    expect(result.unit.name).toBe("cup");
+    expect(result.value).toBeCloseTo(0.5);
+
+    // 0.5 lb (input family) vs 8 oz (integer, other family)
+    const lbDef = normalizeUnit("lb")!;
+    const result2 = findBestUnit(226.796, "mass", "US", [lbDef]);
+    expect(result2.unit.name).toBe("lb");
+    expect(result2.value).toBeCloseTo(0.5);
+
+    // 1.5 cups (input family, non-integer) vs 12 fl-oz (integer, other family)
+    const result3 = findBestUnit(354.882, "volume", "US", [cupDef]);
+    expect(result3.unit.name).toBe("cup");
+    expect(result3.value).toBeCloseTo(1.5);
+  });
+
+  it("should sort multiple non-integer input-family candidates by largest value first", () => {
+    // 350ml in US, input=[cup, fl-oz]: cup≈1.479, fl-oz≈11.834 — both non-integer, both in range
+    // Sort descending by value → fl-oz wins (exercises the sort comparator when 2+ candidates)
+    const cupDef = normalizeUnit("cup")!;
+    const flozDef = normalizeUnit("fl-oz")!;
+    const result = findBestUnit(350, "volume", "US", [cupDef, flozDef]);
+    expect(result.unit.name).toBe("fl-oz");
+    expect(result.value).toBeCloseTo(11.83, 1);
+  });
+
+  it("should pick smallest non-integer in range when input unit is out of range", () => {
+    // 30ml in US with tsp as input: tsp≈6.09 is above maxValue(5) so out of range.
+    // fl-oz≈1.015 and tbsp≈2.03 are both non-integer and in range but not in input family.
+    // Fourth priority picks smallest: fl-oz=1.015 < tbsp=2.03
+    const tspDef = normalizeUnit("tsp")!;
+    const result = findBestUnit(30, "volume", "US", [tspDef]);
+    expect(result.unit.name).toBe("fl-oz");
+    expect(result.value).toBeCloseTo(1.015, 2);
+  });
 });