Flip mix(a, b, w) weight semantics (#59)

`w=0` now returns `a`, and `w=1` returns `b`. Update tests, implementation, and documentation.

Author: stefanvictora

CHANGELOG.md

@@ -1,11 +1,16 @@
+## [0.16.1] - 2026-04-10
+
+### Changed
+- **`mix(a, b, w)` weight semantics flipped**: `w=0` now returns `a` and `w=1` returns `b`, matching the conventional linear interpolation convention. Previously the semantics were reversed.
+
 ## [0.16.0] - 2026-04-06
 
 ### Added
 - **Start time function expressions** (#48): New composable functions for constraining and blending solar and fixed times in start time expressions. All arguments may be fixed times, sun keywords (with optional offset), or nested function calls.
   - `notBefore(expr, min)` — ensures the result is not earlier than `min`; returns the latter of the two. Alias: `max(a, b)`.
   - `notAfter(expr, max)` — ensures the result is not later than `max`; returns the earlier of the two. Alias: `min(a, b)`.
   - `clamp(expr, min, max)` — constrains the result to the `[min, max]` range.
-  - `mix(a, b, weight)` — linearly interpolates between two times with the given `weight` in `[0..1]` or as a percentage (`0%..100%`). A weight of `1` returns `a`, `0` returns `b`. Example: `mix(sunrise, 08:00, 0.35)` blends toward a fixed anchor, softening seasonal drift.
+  - `mix(a, b, weight)` — linearly interpolates between two times with the given `weight` in `[0..1]` or as a percentage (`0%..100%`). Example: `mix(sunrise, 08:00, 0.35)` blends toward a fixed anchor, softening seasonal drift.
   - `smooth(expr, halfLife)` — exponentially smooths a time expression over past days to reduce day-to-day variation. `halfLife` specifies how many days it takes for the smoothing influence to halve (e.g. `14d`). Useful for softening sharp seasonal sunrise/sunset swings. Example: `smooth(sunrise, 14d)`.
   - Functions are case-insensitive and fully composable, e.g. `clamp(smooth(sunrise, 14d), 07:00, 09:00)`.
   - Full documentation is available in the [Light Configuration docs](/docs/light_configuration.md#constraint-functions). 

docs/light_configuration.md

@@ -126,13 +126,13 @@ Bedroom  clamp(smooth(sunrise, 14d), 06:30, 08:00)  bri:30%
 
 #### Experimental: `mix(...)` — blend two time expressions
 
-`mix(a, b, w)` places the trigger time between two time expressions `a` and `b`. The weight `w` controls how close the result is to `a`:
+`mix(a, b, w)` places the trigger time between two time expressions `a` and `b`. The weight `w` controls how close the result is to `b`:
 
-- `w = 1` → exactly `a`
-- `w = 0` → exactly `b`
+- `w = 0` → exactly `a`
+- `w = 1` → exactly `b`
 - `w = 0.5` → midpoint between `a` and `b`
 
-A common use is blending a solar time with a fixed clock time: `mix(sunrise, 07:30, 0.35)` takes sunrise but pulls it 65% toward `07:30` — so the schedule still moves with the seasons, but much more gently. You can also blend two solar times directly: `mix(golden_hour, sunset, 0.5)`. The order of `a` and `b` does not matter — the result is always between the two.
+A common use is blending a solar time with a fixed clock time: `mix(sunrise, 07:30, 0.35)` takes sunrise but pulls it 35% toward `07:30` — so the schedule still moves with the seasons, but much more gently. The result is always between the two endpoints. You can also blend two solar times directly: `mix(golden_hour, sunset, 0.5)`.
 
 **Why use it:** If you like solar-based schedules but want them to behave more like a stable routine (e.g., "around 07:30, but still season-aware"), `mix` **narrows the seasonal range**. However, since both values are recalculated fresh each day, day-to-day jumps are not smoothed out.
 

pom.xml

@@ -6,7 +6,7 @@
 
     <groupId>at.sv.hue</groupId>
     <artifactId>hue-scheduler</artifactId>
-    <version>0.16.0</version>
+    <version>0.16.1-SNAPSHOT</version>
 
     <scm>
         <connection>scm:git:git@github.com:stefanvictora/hue-scheduler.git</connection>

src/main/java/at/sv/hue/HueScheduler.java

@@ -61,7 +61,7 @@
 
 import static at.sv.hue.InputConfigurationParser.parseBrightnessPercentValue;
 
-@Command(name = "HueScheduler", version = "0.16.0", mixinStandardHelpOptions = true, sortOptions = false)
+@Command(name = "HueScheduler", version = "0.16.1", mixinStandardHelpOptions = true, sortOptions = false)
 public final class HueScheduler implements Runnable {
 
     private static final Logger LOG = LoggerFactory.getLogger(HueScheduler.class);

src/main/java/at/sv/hue/time/StartTimeProvider.java

@@ -13,7 +13,8 @@ public interface StartTimeProvider {
      *                 </ul>
      *                 Supported function names are {@code notBefore}, {@code notAfter}, {@code clamp}, {@code min}, {@code max},
      *                 {@code mix}, and {@code smooth}. The {@code mix(a,b,w)} function interpolates between {@code a} and {@code b}
-     *                 with weight {@code w} where {@code w} can be in {@code [0..1]} or as percentage ({@code 0%..100%}).
+     *                 with weight {@code w} (in {@code [0..1]} or as percentage {@code 0%..100%}), where {@code w=0} returns {@code a}
+     *                 and {@code w=1} returns {@code b}.
      *                 The {@code smooth(expr,halfLife)} function exponentially smooths a time expression across past days,
      *                 where {@code halfLife} is specified in days (e.g. {@code 14d}).
      * @param dateTime the date to use a reference for resolving solar times

src/main/java/at/sv/hue/time/StartTimeProviderImpl.java

@@ -94,7 +94,7 @@ private ZonedDateTime parseFunctionExpression(String input, ZonedDateTime dateTi
                 ZonedDateTime a = getStart(args.get(0).trim(), dateTime);
                 ZonedDateTime b = getStart(args.get(1).trim(), dateTime);
                 double weight = parseMixWeight(args.get(2).trim());
-                long mixedEpochSeconds = Math.round(a.toEpochSecond() * weight + b.toEpochSecond() * (1.0 - weight));
+                long mixedEpochSeconds = Math.round(a.toEpochSecond() * (1.0 - weight) + b.toEpochSecond() * weight);
                 return ZonedDateTime.ofInstant(java.time.Instant.ofEpochSecond(mixedEpochSeconds), a.getZone());
             }
             case "smooth" -> {

src/test/java/at/sv/hue/time/StartTimeProviderTest.java

@@ -464,8 +464,8 @@ void notAfter_usesCorrectDate() {
 
     @Test
     void mix_withDecimalWeight_interpolatesTimes() {
-        // mix(sunrise=07:00, 08:00, 0.25) = 07:45
-        assertStart("mix(sunrise, 08:00, 0.25)", now.with(LocalTime.of(7, 45)));
+        // mix(sunrise=07:00, 08:00, 0.25) = 07:15
+        assertStart("mix(sunrise, 08:00, 0.25)", now.with(LocalTime.of(7, 15)));
     }
 
     @Test
@@ -486,31 +486,31 @@ void mix_invertedParameters_stillBlends() {
     }
 
     @Test
-    void mix_aLaterThanB_blendsPullingTowardB() {
+    void mix_aLaterThanB_blendsPullingTowardA() {
         // Simulates winter: sunrise=07:00, anchor=06:30 (sunrise passed the anchor)
-        // mix(07:00, 06:30, 0.35) = 07:00*0.35 + 06:30*0.65 = 06:40:30
-        assertStart("mix(sunrise, 06:30, 0.35)", now.with(LocalTime.of(6, 40, 30)));
+        // mix(07:00, 06:30, 0.35) = 07:00*0.65 + 06:30*0.35 = 06:49:30
+        assertStart("mix(sunrise, 06:30, 0.35)", now.with(LocalTime.of(6, 49, 30)));
     }
 
     @Test
     void mix_withPercentageWeight_interpolatesTimes() {
-        // mix(sunrise=07:00, 08:00, 25%) = 07:45
-        assertStart("mix(sunrise, 08:00, 25%)", now.with(LocalTime.of(7, 45)));
+        // mix(sunrise=07:00, 08:00, 25%) = 07:15
+        assertStart("mix(sunrise, 08:00, 25%)", now.with(LocalTime.of(7, 15)));
     }
 
     @Test
-    void mix_withWeightOne_returnsFirstArgument() {
-        assertStart("mix(sunrise, 08:00, 1)", sunrise);
+    void mix_withWeightOne_returnsSecondArgument() {
+        assertStart("mix(sunrise, 08:00, 1)", now.with(LocalTime.of(8, 0)));
     }
 
     @Test
-    void mix_withWeightZero_returnsSecondArgument() {
-        assertStart("mix(sunrise, 08:00, 0)", now.with(LocalTime.of(8, 0)));
+    void mix_withWeightZero_returnsFirstArgument() {
+        assertStart("mix(sunrise, 08:00, 0)", sunrise);
     }
 
     @Test
     void mix_canBeComposedWithClamp() {
-        assertStart("clamp(mix(sunrise, 08:00, 0.35), 06:30, 08:00)", now.with(LocalTime.of(7, 39)));
+        assertStart("clamp(mix(sunrise, 08:00, 0.35), 06:30, 08:00)", now.with(LocalTime.of(7, 21)));
     }
 
     @Test