@buoy-gg/shared-ui 7.0.26 → 7.0.28

package/lib/module/ui/backgrounds/README.md

@@ -11,27 +11,65 @@ top.
 </View>
 ```
 
-The preset is a single shared, persisted choice (`backgroundStore`), so
-switching it in one tool switches it everywhere. `<BackgroundSwitcher />` is the
-‹ prev / next › review strip used to audition the catalogue.
+The preset is a single shared, persisted choice (`backgroundStore`, default:
+**Hyperspace**), so switching it in one tool switches it everywhere. Shipping
+surfaces get it automatically: `JsModal` and `BottomSheet` mount
+`<ToolBackground />` inside their content box by default (opt out per tool
+with `background={false}`; the network tool does, because it mounts its own so
+the desktop inline panel matches).
 
-## The two families
+`<BackgroundSwitcher />` is the ‹ prev / next › review strip used to audition
+the catalogue (plus Live Sky's time slider and ▶ movie). It is currently
+mounted NOWHERE — the catalogue picked its winner — but stays in the package:
+drop it back at the top of a tool body to audition changes.
+
+## The catalogue
+
+Round 3 cut the set to the keepers plus three underwater variations (round 4
+folded the Meteors preset into Deep Field):
 
-- **Starfield** (`variants/starfield.tsx`) — the cheap scenic preset: 99 stars
-  quantised into five depth bands.
 - **Deep Field** (`variants/deepField.tsx`) — the Everlights
   `ParallaxDriftBackground`, ported 1:1: same seed and generator call order,
   same 160 stars, same far-plane bias, sizes, palette and drift. Speed is
   quantised into 18 bands (a distinct speed costs a distinct animated node);
-  everything else stays per-star. Roughly twice Starfield's cost — the file
-  documents exactly what could and couldn't come across from Skia.
-- **The lattice family** (`variants/lattice.tsx`) — Hex Mesh, Iso Grid,
-  Crosshatch, Perf Board, Halftone, Waffle, Instrument, Radar. Quiet technical
-  geometry: near-black base, one soft off-centre glow, a rasterized hairline
-  pattern at low alpha, a slow breath, a vignette. They read as instrument
-  panels and drafting paper rather than scenery, which is what keeps them
-  legible under dense tool UI. `LatticeShell` owns everything but the geometry,
-  so the family stays a family.
+  everything else stays per-star. The priciest preset — the file documents
+  exactly what could and couldn't come across from Skia. The shipping preset
+  also composes the **meteor layer** (`variants/meteors.tsx`, once its own
+  "Meteors" preset): shooting stars that streak in, hit a WALL of the surface
+  and burst — flash, expanding shockwave ring (half-clipped by the edge, which
+  sells the impact), sparks ricocheting back into the room; each meteor's
+  whole life cycle is keyframed into interpolate stops on one plain loop.
+  `DeepFieldTunable` stays meteor-free for the bench.
+- **Hyperspace** (`variants/hyperspace.tsx`) — the Everlights Skia
+  `HyperspaceBackground` (lightspeed starfield) re-derived for this contract:
+  the per-frame `screen = plane/z` projection becomes scale keyframes on
+  phase-offset shells (a layer scaled by 1/z moves every star on exactly the
+  original's hyperbolic curve), with the wrap snap hidden inside the
+  original's own 6% fade edges. One animated node total; raster OFF on the
+  shells because a cached bitmap scaled 8× goes to mush.
+- **Live Sky** (`variants/liveSky.tsx`) — the cove on the real local clock:
+  sun up 06:30–19:00 on a sine arc, moon on the night shift, dawn/golden/
+  sunset/dusk as lerped palette keyframes (night = Moonlight's palette, noon =
+  Daylight's). ZERO extra animated nodes — the sun moves ~0.4px/minute, so the
+  scene is laid out statically per minute and a once-a-minute AppState-gated
+  tick re-renders it; this also sidesteps the native driver's
+  transform/opacity-only limit for the colour transitions. Discs draw UNDER
+  the opaque sea so the horizon clips a rising/setting body for free. While
+  it's showing, the switcher grows a time slider (writes `skyClock.ts`,
+  5-minute quantized, not persisted) to scrub the whole cycle by hand; LIVE
+  snaps back to the clock. See `LIVE_SKY_PLAN.md`.
+- **The underwater family** (`variants/underwater.tsx`) — Abyss, Bubbles,
+  Jellyfish. One register — lit from the surface, near-black at the bottom,
+  motion in tens of seconds — with different life in the water: marine snow,
+  rising bubbles (a ring plus an off-centre highlight is what makes a bubble),
+  and pulsing jellies that traverse bottom-to-top entirely off-screen at the
+  loop seam.
+
+Catalogue trims (2026-08-20): Off, Night Drift, Moonlight, Daylight, Kelp and
+Kelp Forest were cut from the registry. `variants/moonlight.tsx` and
+`variants/daylight.tsx` stay in the tree — Live Sky's palettes are documented
+against them and the bg-bench lanes (`MoonlightTunable`/`DaylightTunable`)
+still drive them — they just aren't offered in the switcher.
 
 ## The constraint
 
@@ -58,6 +96,15 @@ translucent layers. For the same reason nothing here uses `transformOrigin`
 
 Loops stop when the app backgrounds, and unmount with the tool.
 
+4. **Geometry never scales with the modal.** Resizing the surface must crop
+   the scene, not stretch it — rays, plants, blooms and particles size
+   themselves from `Dimensions.get("window")` and only their POSITIONS
+   distribute across the measured width/height (the preset root clips with
+   `overflow: "hidden"`). Smooth gradients (base washes, vignettes) may track
+   the live size — their scaling is imperceptible. The one sanctioned
+   exception is geometry that is ABOUT the surface itself, like the meteors'
+   wall-impact points.
+
 **Known trap:** `Animated.sequence([timing, Animated.loop(...)])` silently fails
 to drive the value on the native driver — no warning, the field renders and
 never moves. It's the obvious way to phase-offset siblings; don't. Stagger via
@@ -66,8 +113,9 @@ different periods, or bake the offset into the `interpolate`.
 ### Measured
 
 Network tool open on an iPhone 16 simulator, via perf-monitor and
-`measure_renders`. Starfield is the heaviest preset (6 animated nodes, ~222
-static views); the lattice presets are 1–2 nodes and 40–176 views.
+`measure_renders`. (Starfield and the lattice presets were measured before the
+round-3 cull; the rows stay as calibration points — Deep Field is still the
+ceiling, and the newer presets all run 3–7 nodes.)
 
 **Steady state** — 12–13s idle recordings:
 
@@ -87,6 +135,40 @@ The commits in every column are the network tool's own once-a-minute
 reported one component render in every configuration — the animation contributes
 zero React work while it runs, which is rule 1 holding regardless of node count.
 
+**Moonlight v3** (buoy-optimize loop, iPhone 17 Pro sim, bg-bench, 3-run
+medians, reproduced across two batches):
+
+| | UI FPS | UI jank | JS FPS |
+|---|---:|---:|---:|
+| control (no background) | 60.0 | 0 | 58.3 |
+| Moonlight, shipping (~330 views, 5 nodes) | 59.9 | 0 | 57.5–58.1 |
+| glade ×12 (~1.2k blocks) | 59.5 | 0 | 57.0 |
+| glade ×30 (~3.1k blocks) | 56.4–56.8 | 2 | 53.8 |
+
+Shipping Moonlight is indistinguishable from no background; the UI cliff sits
+between 12× and 30× the shipping glade. Structural variants (fused glade,
+raster off, chrome off) all tied with shipping at 1× AND failed to separate at
+×30 (±1 FPS, and raster-off ballooned memory 287→351MB), so the shipping
+structure stays. Bench lane: `bg-bench?v=ml-*` drives `MoonlightTunable`.
+
+**Confirmed on a real iPhone SE (375×667, 60Hz)** — both in-batch controls
+held 60.0/0 (zero drift): ship 59.6 UI / 0 UI jank; ×12 58.8 / 1; ×30 breaks
+(54.4 UI, CPU 57). Same ranking as the sim; the sim → device carry-over held.
+
+**Animated vs static (real iPhone, same batch):** identical — 59.6 UI / 0
+jank / 0 JS jank both; static saved ~2.7 CPU points, less than the batch's
+own control-to-control CPU spread (4.4), though the direction repeated on the
+sim (~2.4). The motion toggle is a preference, not a perf lever, at shipping
+scale — which is the native-driver contract holding. (A JS-jank scare in an
+earlier batch attributed ~3 events to the ml cases; a later batch put 4 on a
+CONTROL, so those are between-case reload noise.)
+
+**Benchmark-protocol note:** the batch's FINAL case is unreliable — in two
+consecutive batches the trailing control recorded byte-identical bad numbers
+(53.7 UI FPS, 4 JS jank, only 2/3 runs) while an identical control at slot 1
+was clean, so the batch teardown bleeds into the last recording. End every
+batch with a sacrificial case, the same way it starts with one.
+
 **Mount** — the cost that is real for all of them:
 
 ```
@@ -110,6 +192,6 @@ Add the component to `variants/`, then one entry in `registry.tsx` with an
 honest `nodes` (animated nodes) and `views` (static views at ~380×620). The
 switcher shows both, which is the point — it's a review tool, not decoration.
 
-Alpha calibration: Hex Mesh is the reference. Anything fainter than its lattice
-disappears under the vignette — hairline strokes in particular need ~0.2 alpha
-or a second pixel of height to register at all.
+Alpha calibration: every preset runs a 0.4–0.55 vignette, and anything fainter
+than ~0.2 alpha disappears under it — hairline strokes in particular need ~0.2
+alpha or a second pixel of height to register at all.

package/lib/module/ui/backgrounds/backgroundStore.js

@@ -14,7 +14,20 @@ import { useEffect, useState } from "react";
 import { devToolsStorageKeys } from "../../storage/devToolsStorageKeys.js";
 import { persistentStorage } from "../../utils/persistentStorage.js";
 import { BACKGROUND_PRESETS, DEFAULT_BACKGROUND, presetAt, presetIndex } from "./registry.js";
-const KEY = `${devToolsStorageKeys.base}_tool_background`;
+// v3: bumped when the default became "off" (backgrounds are opt-in now), so
+// devices that stepped the switcher during the (unreleased) audition rounds
+// re-default to none instead of keeping a pre-release pick forever. Earlier
+// keys are simply abandoned, same as v1 was.
+const KEY = `${devToolsStorageKeys.base}_tool_background_v3`;
+
+/** The persisted-selection key, exported so a host can ask "has the user ever
+ * picked a background?" (the desktop's first-run hint modal reads it). */
+export const BACKGROUND_STORAGE_KEY = KEY;
+
+// Motion is deliberately NOT persisted: the switcher no longer offers a
+// motion toggle, so every session starts animated. `setMotion` survives as a
+// session-only seam (bench harnesses, a tool forcing stillness).
+
 function isValidId(value) {
   return typeof value === "string" && BACKGROUND_PRESETS.some(p => p.id === value);
 }
@@ -47,8 +60,10 @@ class BackgroundStore {
         const raw = await persistentStorage.getItem(KEY);
         if (!raw || this.dirty) return;
         const parsed = JSON.parse(raw);
-        if (isValidId(parsed.id)) this.id = parsed.id;
-        if (typeof parsed.motion === "boolean") this.motion = parsed.motion;
+        // The standalone Meteors preset was folded into Deep Field — re-home
+        // anyone still persisted on it rather than dropping them to the default.
+        const id = parsed.id === "meteors" ? "deepfield" : parsed.id;
+        if (isValidId(id)) this.id = id;
         this.notify();
       } catch {
         // A missing or corrupt entry just means "use the default".
@@ -59,8 +74,7 @@ class BackgroundStore {
   persist() {
     this.dirty = true;
     const payload = {
-      id: this.id,
-      motion: this.motion
+      id: this.id
     };
     void persistentStorage.setItem(KEY, JSON.stringify(payload)).catch(() => {});
   }

package/lib/module/ui/backgrounds/index.js

@@ -2,8 +2,17 @@
 
 export { ToolBackground } from "./ToolBackground.js";
 export { BackgroundSwitcher } from "./BackgroundSwitcher.js";
-export { backgroundStore, useToolBackground } from "./backgroundStore.js";
+export { backgroundStore, BACKGROUND_STORAGE_KEY, useToolBackground } from "./backgroundStore.js";
 export { BACKGROUND_PRESETS, DEFAULT_BACKGROUND, getPreset, presetAt, presetIndex } from "./registry.js";
+// Drawing/animation primitives, exported so other Buoy chrome (the dial menu's
+// snow effect in @buoy-gg/core) can build matching effects under the same
+// native-driven performance contract instead of copying the implementations.
+export { LinearFade, RadialGlow, RasterLayer, useLoop, usePulse } from "./primitives.js";
+export { scatter, withAlpha as withBgAlpha } from "./rng.js";
 // Exported for the bg-bench harness in example-dev-build, so every measured
 // variant is the shipping component with knobs turned rather than a copy.
-export { DeepFieldTunable } from "./variants/deepField.js";
+export { DeepFieldTunable } from "./variants/deepField.js";
+export { MoonlightTunable } from "./variants/moonlight.js";
+export { DaylightTunable } from "./variants/daylight.js";
+export { LiveSkyTunable } from "./variants/liveSky.js";
+export { getSkyScrub, setSkyScrub, useSkyScrub } from "./skyClock.js";

package/lib/module/ui/backgrounds/primitives.js

@@ -15,7 +15,9 @@
  *     looping `Animated.timing` means the whole loop is handed to the UI thread
  *     once and never touches JS again — no per-frame callback, no re-render, no
  *     bridge traffic while it runs. A preset animates a handful of *layers*
- *     (transform on one parent view), never per-particle.
+ *     (transform on one parent view), never per-particle. (On web there is no
+ *     native driver and the JS driver must be requested explicitly — see
+ *     NATIVE_DRIVER below for why the flag can't simply be left `true`.)
  *
  *  2. **Every static layer is rasterized.** `shouldRasterizeIOS` /
  *     `renderToHardwareTextureAndroid` turn a layer of 40 dots into a single
@@ -29,21 +31,35 @@
 import { memo, useEffect, useRef } from "react";
 import { Animated, AppState, Easing, Platform, StyleSheet, View } from "react-native";
 import { absoluteFill } from "../../utils/absoluteFill.js";
-import { withAlpha } from "./rng.js";
+import { flattenOver, withAlpha } from "./rng.js";
 
 // ============================================================================
 // Animation
 // ============================================================================
 
 /**
- * A native-driven 0→1 loop.
+ * Ask for the native driver ONLY where the native animated module exists.
+ *
+ * On react-native-web (the desktop dashboard) `useNativeDriver: true` is
+ * demoted to the JS driver — but `Animated.loop` trusts the config flag, not
+ * the demotion: for a bare `loop(timing(...))` it takes its native-loop
+ * shortcut and starts ONE plain timing whose `iterations: -1` only the
+ * (absent) native module would honor. The loop plays a single pass and
+ * freezes — on desktop every background stopped seconds after opening.
+ * Requesting the JS driver honestly keeps loop's JS restart path in charge,
+ * which is the only driver web has anyway.
+ */
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+const NATIVE_DRIVER = Platform.OS !== "web";
+
+/**
+ * A native-driven 0→1 loop (JS-driven on web — see NATIVE_DRIVER).
  *
  * The returned value is only ever consumed by `interpolate` inside an
  * `Animated.View` style, so React never re-renders while it runs. The loop is
  * stopped when the app backgrounds (a background animation is pure battery
  * burn) and restarted on foreground.
  */
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 export function useLoop(durationMs, enabled = true) {
   const value = useRef(new Animated.Value(0)).current;
   useEffect(() => {
@@ -56,7 +72,11 @@ export function useLoop(durationMs, enabled = true) {
         toValue: 1,
         duration: durationMs,
         easing: Easing.linear,
-        useNativeDriver: true
+        useNativeDriver: NATIVE_DRIVER,
+        // A decorative endless loop must never register as an interaction —
+        // the default (true) would block InteractionManager callbacks in the
+        // host app for as long as the background is mounted.
+        isInteraction: false
       }));
       anim.start();
     };
@@ -93,12 +113,16 @@ export function usePulse(durationMs, enabled = true) {
         toValue: 1,
         duration: durationMs / 2,
         easing: Easing.inOut(Easing.quad),
-        useNativeDriver: true
+        useNativeDriver: NATIVE_DRIVER,
+        // See useLoop: endless decorative loops must not hold
+        // InteractionManager (isInteraction defaults to true).
+        isInteraction: false
       }), Animated.timing(value, {
         toValue: 0,
         duration: durationMs / 2,
         easing: Easing.inOut(Easing.quad),
-        useNativeDriver: true
+        useNativeDriver: NATIVE_DRIVER,
+        isInteraction: false
       })]));
       anim.start();
     };
@@ -193,7 +217,18 @@ export const RadialGlow = /*#__PURE__*/memo(function RadialGlow({
 /**
  * Fake linear gradient: `bands` stacked strips with linearly interpolated
  * alpha. Used for scrims (keep text readable over a busy field) and for
- * horizon glows. 12–16 bands is invisible as banding at these alphas.
+ * horizon glows.
+ *
+ * TRAP (found on the Abyss wash): translucent strips must NOT overlap. An
+ * overlap composites the same colour twice, doubling the alpha in a stripe at
+ * every band edge — on a dark surface that draws a visible line per band, and
+ * because the strips are %-sized the whole ruled pattern rescales as the
+ * modal resizes. Strips here butt exactly, with a 0.08% fudge (sub-pixel at
+ * any real size) so layout rounding can't open a hairline gap.
+ *
+ * `flattenBase`: when the fade sits DIRECTLY on a known opaque colour, pass
+ * that colour — each strip is then drawn opaque via `flattenOver`, which is
+ * pixel-identical, immune to seams entirely, and cheaper to composite.
  */
 export const LinearFade = /*#__PURE__*/memo(function LinearFade({
   color,
@@ -201,6 +236,7 @@ export const LinearFade = /*#__PURE__*/memo(function LinearFade({
   to = 1,
   bands = 14,
   direction = "down",
+  flattenBase,
   style
 }) {
   const vertical = direction === "down" || direction === "up";
@@ -210,21 +246,22 @@ export const LinearFade = /*#__PURE__*/memo(function LinearFade({
   for (let i = 0; i < bands; i++) {
     const t = (i + 0.5) / bands;
     const a = from + (to - from) * (reversed ? 1 - t : t);
+    const fill = flattenBase ? flattenOver(color, a, flattenBase) : withAlpha(color, a);
     strips.push(/*#__PURE__*/_jsx(View, {
       style: vertical ? {
         position: "absolute",
         left: 0,
         right: 0,
         top: `${i * pct}%`,
-        height: `${pct + 1.2}%`,
-        backgroundColor: withAlpha(color, a)
+        height: `${pct + 0.08}%`,
+        backgroundColor: fill
       } : {
         position: "absolute",
         top: 0,
         bottom: 0,
         left: `${i * pct}%`,
-        width: `${pct + 1.2}%`,
-        backgroundColor: withAlpha(color, a)
+        width: `${pct + 0.08}%`,
+        backgroundColor: fill
       }
     }, i));
   }
@@ -263,7 +300,7 @@ export const Vignette = /*#__PURE__*/memo(function Vignette({
         from: alpha,
         to: 0,
         direction: "down",
-        bands: 10
+        bands: 14
       })
     }), /*#__PURE__*/_jsx(View, {
       style: {
@@ -278,7 +315,7 @@ export const Vignette = /*#__PURE__*/memo(function Vignette({
         from: 0,
         to: alpha,
         direction: "down",
-        bands: 10
+        bands: 14
       })
     }), /*#__PURE__*/_jsx(View, {
       style: {
@@ -293,7 +330,7 @@ export const Vignette = /*#__PURE__*/memo(function Vignette({
         from: alpha,
         to: 0,
         direction: "right",
-        bands: 8
+        bands: 10
       })
     }), /*#__PURE__*/_jsx(View, {
       style: {
@@ -308,7 +345,7 @@ export const Vignette = /*#__PURE__*/memo(function Vignette({
         from: 0,
         to: alpha,
         direction: "right",
-        bands: 8
+        bands: 10
       })
     })]
   });

package/lib/module/ui/backgrounds/registry.js

@@ -10,88 +10,65 @@
  * them honest.
  */
 
-import { Crosshatch, Halftone, HexMesh, Instrument, IsoGrid, PerfBoard, Radar, Waffle } from "./variants/lattice.js";
 import { DeepField } from "./variants/deepField.js";
-import { Starfield } from "./variants/starfield.js";
+import { Hyperspace } from "./variants/hyperspace.js";
+import { LiveSky } from "./variants/liveSky.js";
+import { Abyss, Bubbles, Jellyfish } from "./variants/underwater.js";
 export const BACKGROUND_PRESETS = [{
   id: "off",
   label: "Off",
-  blurb: "Plain black — the baseline to compare against",
+  blurb: "Plain black — no backdrop at all",
   nodes: 0,
   views: 1,
   Component: null
-}, {
-  id: "starfield",
-  label: "Starfield",
-  blurb: "Five depth bands drifting at parallax speeds",
-  nodes: 6,
-  views: 222,
-  Component: Starfield
 }, {
   id: "deepfield",
   label: "Deep Field",
-  blurb: "The Everlights field, 1:1 — 160 stars, richer but pricier",
-  nodes: 22,
-  views: 462,
+  blurb: "The Everlights field — 160 stars, with meteors slamming the walls",
+  // The old standalone Meteors preset folded in: +2 meteor loops, ~50 views.
+  nodes: 24,
+  views: 510,
   Component: DeepField
 }, {
-  id: "hexmesh",
-  label: "Hex Mesh",
-  blurb: "Diamond lattice with a slow breath",
-  nodes: 1,
-  views: 160,
-  Component: HexMesh
-}, {
-  id: "isogrid",
-  label: "Iso Grid",
-  blurb: "Three-axis isometric ruling",
+  id: "hyperspace",
+  label: "Hyperspace",
+  blurb: "Lightspeed — crisp points streaming from a centre vanishing point",
   nodes: 1,
-  views: 66,
-  Component: IsoGrid
+  views: 570,
+  Component: Hyperspace
 }, {
-  id: "crosshatch",
-  label: "Crosshatch",
-  blurb: "Fine 45° weave, drafting-paper quiet",
-  nodes: 1,
-  views: 64,
-  Component: Crosshatch
+  id: "livesky",
+  label: "Live Sky",
+  blurb: "The cove on your clock — dawn to dusk, for real",
+  nodes: 5,
+  views: 290,
+  Component: LiveSky
 }, {
-  id: "perfboard",
-  label: "Perf Board",
-  blurb: "Solder-pad matrix with datum pads every fourth",
-  nodes: 1,
-  views: 150,
-  Component: PerfBoard
+  id: "abyss",
+  label: "Abyss",
+  blurb: "A surface light fanning into the deep",
+  nodes: 4,
+  views: 230,
+  Component: Abyss
 }, {
-  id: "halftone",
-  label: "Halftone",
-  blurb: "Dot grid swelling toward the light",
-  nodes: 1,
-  views: 176,
-  Component: Halftone
+  id: "bubbles",
+  label: "Bubbles",
+  blurb: "Bubbles wobbling up through the light",
+  nodes: 4,
+  views: 180,
+  Component: Bubbles
 }, {
-  id: "waffle",
-  label: "Waffle",
-  blurb: "Machined panel of rounded cells",
-  nodes: 1,
-  views: 88,
-  Component: Waffle
-}, {
-  id: "instrument",
-  label: "Instrument",
-  blurb: "Ruled scales with major graduations",
-  nodes: 1,
-  views: 110,
-  Component: Instrument
-}, {
-  id: "radar",
-  label: "Radar",
-  blurb: "Rings and spokes under a rotating sweep",
-  nodes: 2,
-  views: 40,
-  Component: Radar
+  id: "jellyfish",
+  label: "Jellyfish",
+  blurb: "A bloom of glowing jellies, big and small, pulsing past",
+  nodes: 15,
+  views: 250,
+  Component: Jellyfish
 }];
-export const DEFAULT_BACKGROUND = "hexmesh";
+
+// Ships OFF: a backdrop is an opt-in, so first load is plain black and the
+// choice only persists once the user actually picks one in the switcher.
+export const DEFAULT_BACKGROUND = "off";
 export function presetIndex(id) {
   const i = BACKGROUND_PRESETS.findIndex(p => p.id === id);
   return i < 0 ? 0 : i;

package/lib/module/ui/backgrounds/rng.js

@@ -42,6 +42,26 @@ export function withAlpha(hex, alpha) {
   return `rgba(${r},${g},${b},${a.toFixed(3)})`;
 }
 
+/**
+ * RGB lerp between two `#RRGGBB` (or `#RGB`) colours, returned as `#RRGGBB`.
+ * Used by Live Sky to blend palette keyframes; at minute-sized steps a plain
+ * RGB lerp is indistinguishable from anything fancier.
+ */
+export function lerpColor(a, b, t) {
+  const parse = h => {
+    let v = h.replace("#", "");
+    if (v.length === 3) v = v[0] + v[0] + v[1] + v[1] + v[2] + v[2];
+    const n = parseInt(v, 16);
+    return [n >> 16 & 255, n >> 8 & 255, n & 255];
+  };
+  const [ar, ag, ab] = parse(a);
+  const [br, bg, bb] = parse(b);
+  const c = t < 0 ? 0 : t > 1 ? 1 : t;
+  const mix = (x, y) => Math.round(x + (y - x) * c);
+  const hex = n => n.toString(16).padStart(2, "0");
+  return `#${hex(mix(ar, br))}${hex(mix(ag, bg))}${hex(mix(ab, bb))}`;
+}
+
 /**
  * `hex` at `alpha` composited over an opaque `base`, returned as an OPAQUE
  * colour.

package/lib/module/ui/backgrounds/skyClock.js

@@ -0,0 +1,39 @@
+"use strict";
+
+/**
+ * The Live Sky scrub clock.
+ *
+ * `null` means "live" — the Live Sky preset follows the real local clock. A
+ * number (minutes since midnight, quantized by the slider) freezes the scene
+ * at that time of day so the whole cycle can be scrubbed through by hand.
+ *
+ * Deliberately NOT part of `backgroundStore`: the variant itself has to read
+ * this, and a variant importing the store would close an import cycle through
+ * the registry (store → registry → variant → store). It is also deliberately
+ * not persisted — a scrub is a preview gesture, not a setting.
+ */
+
+import { useEffect, useState } from "react";
+let scrub = null;
+const listeners = new Set();
+export function getSkyScrub() {
+  return scrub;
+}
+export function setSkyScrub(value) {
+  if (value === scrub) return;
+  scrub = value;
+  for (const listener of listeners) listener();
+}
+
+/** Subscribe a component to the scrub value. */
+export function useSkyScrub() {
+  const [value, setValue] = useState(scrub);
+  useEffect(() => {
+    const listener = () => setValue(scrub);
+    listeners.add(listener);
+    return () => {
+      listeners.delete(listener);
+    };
+  }, []);
+  return value;
+}