@buoy-gg/shared-ui 7.0.26 → 7.0.28

package/lib/commonjs/ui/backgrounds/BackgroundSwitcher.js

@@ -10,87 +10,205 @@ var _lucideIcons = require("../../icons/lucide-icons.js");
 var _macOSDesignSystemColors = require("../gameUI/constants/macOSDesignSystemColors.js");
 var _backgroundStore = require("./backgroundStore.js");
 var _registry = require("./registry.js");
+var _skyClock = require("./skyClock.js");
 var _jsxRuntime = require("react/jsx-runtime");
 /**
- * The ‹ prev / next › strip for auditioning backgrounds.
+ * The ‹ prev / next › strip for choosing a background.
  *
- * This is a REVIEW control, not shipped chrome: it exists so the whole
- * catalogue can be walked without a rebuild, with the cost of each preset shown
- * next to its name. Mount it at the top of a tool's body while evaluating, and
- * pull it once a winner is picked (or keep it behind a setting).
+ * Shipping mount: the dial menu's settings modal (pass `embedded` there so the
+ * host card supplies the chrome). It can also be dropped at the top of a
+ * tool's body while auditioning new presets — the cost of each preset shows
+ * next to its name, so it doubles as the review tool it started as.
  *
  * It writes to the shared `backgroundStore`, so stepping here changes the
  * background in every tool at once.
+ *
+ * While Live Sky is showing, a second row appears: a WALL-clock slider that
+ * scrubs the scene through the whole cycle (Live Sky applies its workday
+ * remap to whatever wall time the scrub holds, same as it does to the live
+ * clock). LIVE snaps back to the real clock. The scrub is quantized to
+ * 5-minute steps so a drag re-renders the scene at most once per step, and it
+ * is not persisted — it's a preview gesture.
+ *
+ * ▶ runs the cycle like a movie: one full 24h lap in 15s, starting from the
+ * displayed time and finishing exactly where it began (back on LIVE if that's
+ * where it was). It drives the SAME scrub value on a JS interval — ~19 5-min
+ * steps a second, each one small re-render of the scene — which is fine for a
+ * 15s preview gesture and is exactly what a fast drag already does.
  */
 
-const BackgroundSwitcher = exports.BackgroundSwitcher = /*#__PURE__*/(0, _react.memo)(function BackgroundSwitcher() {
+const THUMB = 14;
+function formatMinutes(m) {
+  const h = Math.floor(m / 60) % 24;
+  const min = m % 60;
+  return `${String(h).padStart(2, "0")}:${String(min).padStart(2, "0")}`;
+}
+const PLAY_DURATION_MS = 15000;
+const PLAY_FRAME_MS = 50;
+const TimeSlider = /*#__PURE__*/(0, _react.memo)(function TimeSlider() {
+  const scrub = (0, _skyClock.useSkyScrub)();
+  const [trackW, setTrackW] = (0, _react.useState)(0);
+  const widthRef = (0, _react.useRef)(0);
+  const [playing, setPlaying] = (0, _react.useState)(false);
+  const playTimer = (0, _react.useRef)(null);
+  const stopPlay = () => {
+    if (playTimer.current) clearInterval(playTimer.current);
+    playTimer.current = null;
+    setPlaying(false);
+  };
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  (0, _react.useEffect)(() => stopPlay, []);
+  const startPlay = () => {
+    stopPlay();
+    const now = new Date();
+    const startMinutes = (0, _skyClock.getSkyScrub)() ?? now.getHours() * 60 + now.getMinutes();
+    const wasLive = (0, _skyClock.getSkyScrub)() === null;
+    const begin = Date.now();
+    setPlaying(true);
+    playTimer.current = setInterval(() => {
+      const t = (Date.now() - begin) / PLAY_DURATION_MS;
+      if (t >= 1) {
+        stopPlay();
+        // Finish exactly where the day began.
+        (0, _skyClock.setSkyScrub)(wasLive ? null : startMinutes);
+        return;
+      }
+      (0, _skyClock.setSkyScrub)(Math.floor((startMinutes + t * 1440) % 1440 / 5) * 5);
+    }, PLAY_FRAME_MS);
+  };
+  const applyX = x => {
+    stopPlay();
+    const w = widthRef.current;
+    if (w <= 0) return;
+    const frac = Math.min(1, Math.max(0, x / w));
+    (0, _skyClock.setSkyScrub)(Math.round(frac * 1439 / 5) * 5);
+  };
+  const responder = (0, _react.useRef)(_reactNative.PanResponder.create({
+    onStartShouldSetPanResponder: () => true,
+    onMoveShouldSetPanResponder: () => true,
+    onPanResponderGrant: e => applyX(e.nativeEvent.locationX),
+    onPanResponderMove: e => applyX(e.nativeEvent.locationX)
+  })).current;
+  const now = new Date();
+  // Wall time throughout — the scene applies its own remap to this.
+  const minutes = scrub ?? now.getHours() * 60 + now.getMinutes();
+  const frac = minutes / 1440;
+  return /*#__PURE__*/(0, _jsxRuntime.jsxs)(_reactNative.View, {
+    style: styles.sliderRow,
+    children: [/*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.TouchableOpacity, {
+      onPress: () => {
+        stopPlay();
+        (0, _skyClock.setSkyScrub)(null);
+      },
+      style: [styles.live, scrub === null ? styles.liveOn : null],
+      hitSlop: HIT_SLOP,
+      accessibilityLabel: "Follow the real clock",
+      "sentry-label": "ignore background sky live",
+      children: /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.Text, {
+        style: [styles.liveText, scrub === null ? styles.liveTextOn : null],
+        children: "LIVE"
+      })
+    }), /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.TouchableOpacity, {
+      onPress: playing ? stopPlay : startPlay,
+      style: [styles.live, playing ? styles.playOn : null],
+      hitSlop: HIT_SLOP,
+      accessibilityLabel: playing ? "Stop the day cycle" : "Play the full day in 15 seconds",
+      "sentry-label": "ignore background sky play",
+      children: /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.Text, {
+        style: [styles.liveText, playing ? styles.playTextOn : null],
+        children: playing ? "■" : "▶"
+      })
+    }), /*#__PURE__*/(0, _jsxRuntime.jsxs)(_reactNative.View, {
+      style: styles.track,
+      onLayout: e => {
+        widthRef.current = e.nativeEvent.layout.width;
+        setTrackW(e.nativeEvent.layout.width);
+      },
+      ...responder.panHandlers,
+      children: [/*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.View, {
+        style: styles.trackBar,
+        pointerEvents: "none"
+      }), trackW > 0 ? /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.View, {
+        pointerEvents: "none",
+        style: [styles.thumb, scrub === null ? null : styles.thumbScrub, {
+          left: frac * trackW - THUMB / 2
+        }]
+      }) : null]
+    }), /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.Text, {
+      style: styles.time,
+      children: formatMinutes(minutes)
+    })]
+  });
+});
+const BackgroundSwitcher = exports.BackgroundSwitcher = /*#__PURE__*/(0, _react.memo)(function BackgroundSwitcher({
+  embedded = false
+}) {
   const {
     id,
     index,
     count,
-    motion,
     next,
     previous,
-    setMotion
+    setId
   } = (0, _backgroundStore.useToolBackground)();
   const preset = (0, _registry.getPreset)(id);
+  const counterpart = preset.counterpart;
   return /*#__PURE__*/(0, _jsxRuntime.jsxs)(_reactNative.View, {
-    style: styles.root,
-    children: [/*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.TouchableOpacity, {
-      onPress: previous,
-      style: styles.step,
-      hitSlop: HIT_SLOP,
-      accessibilityLabel: "Previous background",
-      "sentry-label": "ignore background previous",
-      children: /*#__PURE__*/(0, _jsxRuntime.jsx)(_lucideIcons.ChevronLeft, {
-        size: 16,
-        color: _macOSDesignSystemColors.macOSColors.text.secondary
-      })
-    }), /*#__PURE__*/(0, _jsxRuntime.jsxs)(_reactNative.View, {
-      style: styles.center,
-      children: [/*#__PURE__*/(0, _jsxRuntime.jsxs)(_reactNative.View, {
-        style: styles.titleRow,
-        children: [/*#__PURE__*/(0, _jsxRuntime.jsx)(_lucideIcons.Palette, {
-          size: 11,
-          color: _macOSDesignSystemColors.macOSColors.semantic.info
+    style: embedded ? styles.rootEmbedded : styles.root,
+    children: [/*#__PURE__*/(0, _jsxRuntime.jsxs)(_reactNative.View, {
+      style: styles.row,
+      children: [/*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.TouchableOpacity, {
+        onPress: previous,
+        style: styles.step,
+        hitSlop: HIT_SLOP,
+        accessibilityLabel: "Previous background",
+        "sentry-label": "ignore background previous",
+        children: /*#__PURE__*/(0, _jsxRuntime.jsx)(_lucideIcons.ChevronLeft, {
+          size: 16,
+          color: _macOSDesignSystemColors.macOSColors.text.secondary
+        })
+      }), /*#__PURE__*/(0, _jsxRuntime.jsxs)(_reactNative.View, {
+        style: styles.center,
+        children: [/*#__PURE__*/(0, _jsxRuntime.jsxs)(_reactNative.View, {
+          style: styles.titleRow,
+          children: [/*#__PURE__*/(0, _jsxRuntime.jsx)(_lucideIcons.Palette, {
+            size: 11,
+            color: _macOSDesignSystemColors.macOSColors.semantic.info
+          }), /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.Text, {
+            style: styles.title,
+            numberOfLines: 1,
+            children: preset.label
+          }), /*#__PURE__*/(0, _jsxRuntime.jsxs)(_reactNative.Text, {
+            style: styles.counter,
+            children: [index + 1, "/", count]
+          })]
         }), /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.Text, {
-          style: styles.title,
+          style: styles.blurb,
           numberOfLines: 1,
-          children: preset.label
-        }), /*#__PURE__*/(0, _jsxRuntime.jsxs)(_reactNative.Text, {
-          style: styles.counter,
-          children: [index + 1, "/", count]
+          children: preset.blurb
         })]
-      }), /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.Text, {
-        style: styles.blurb,
-        numberOfLines: 1,
-        children: preset.blurb
-      }), /*#__PURE__*/(0, _jsxRuntime.jsxs)(_reactNative.Text, {
-        style: styles.cost,
-        numberOfLines: 1,
-        children: [preset.nodes === 0 ? "0 animated nodes" : `${preset.nodes} native node${preset.nodes === 1 ? "" : "s"}`, "  ·  ", "~", preset.views, " static views"]
+      }), counterpart ? /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.TouchableOpacity, {
+        onPress: () => setId(counterpart.id),
+        style: styles.motion,
+        hitSlop: HIT_SLOP,
+        accessibilityLabel: `Switch to ${counterpart.id} background`,
+        "sentry-label": "ignore background counterpart",
+        children: /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.Text, {
+          style: styles.motionText,
+          children: counterpart.label
+        })
+      }) : null, /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.TouchableOpacity, {
+        onPress: next,
+        style: styles.step,
+        hitSlop: HIT_SLOP,
+        accessibilityLabel: "Next background",
+        "sentry-label": "ignore background next",
+        children: /*#__PURE__*/(0, _jsxRuntime.jsx)(_lucideIcons.ChevronRight, {
+          size: 16,
+          color: _macOSDesignSystemColors.macOSColors.text.secondary
+        })
       })]
-    }), /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.TouchableOpacity, {
-      onPress: () => setMotion(!motion),
-      style: [styles.motion, motion ? styles.motionOn : null],
-      hitSlop: HIT_SLOP,
-      accessibilityLabel: motion ? "Turn motion off" : "Turn motion on",
-      "sentry-label": "ignore background motion",
-      children: /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.Text, {
-        style: [styles.motionText, motion ? styles.motionTextOn : null],
-        children: motion ? "MOTION" : "STATIC"
-      })
-    }), /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.TouchableOpacity, {
-      onPress: next,
-      style: styles.step,
-      hitSlop: HIT_SLOP,
-      accessibilityLabel: "Next background",
-      "sentry-label": "ignore background next",
-      children: /*#__PURE__*/(0, _jsxRuntime.jsx)(_lucideIcons.ChevronRight, {
-        size: 16,
-        color: _macOSDesignSystemColors.macOSColors.text.secondary
-      })
-    })]
+    }), id === "livesky" ? /*#__PURE__*/(0, _jsxRuntime.jsx)(TimeSlider, {}) : null]
   });
 });
 const HIT_SLOP = {
@@ -101,9 +219,6 @@ const HIT_SLOP = {
 };
 const styles = _reactNative.StyleSheet.create({
   root: {
-    flexDirection: "row",
-    alignItems: "center",
-    gap: 8,
     paddingHorizontal: 8,
     paddingVertical: 6,
     marginHorizontal: 8,
@@ -116,6 +231,14 @@ const styles = _reactNative.StyleSheet.create({
     // previewing, so you can see the field through it.
     backgroundColor: "rgba(26,26,28,0.72)"
   },
+  rootEmbedded: {
+    // The host card supplies border/fill/margins.
+  },
+  row: {
+    flexDirection: "row",
+    alignItems: "center",
+    gap: 8
+  },
   step: {
     width: 28,
     height: 28,
@@ -150,12 +273,6 @@ const styles = _reactNative.StyleSheet.create({
     fontSize: 10,
     marginTop: 1
   },
-  cost: {
-    color: _macOSDesignSystemColors.macOSColors.text.icon,
-    fontSize: 9,
-    marginTop: 1,
-    fontVariant: ["tabular-nums"]
-  },
   motion: {
     paddingHorizontal: 7,
     paddingVertical: 4,
@@ -164,17 +281,74 @@ const styles = _reactNative.StyleSheet.create({
     borderColor: _macOSDesignSystemColors.macOSColors.border.default,
     backgroundColor: "rgba(38,38,42,0.8)"
   },
-  motionOn: {
-    borderColor: _macOSDesignSystemColors.macOSColors.semantic.info + "55",
-    backgroundColor: _macOSDesignSystemColors.macOSColors.semantic.infoBackground
-  },
   motionText: {
     fontSize: 9,
     fontWeight: "700",
     letterSpacing: 0.6,
     color: _macOSDesignSystemColors.macOSColors.text.muted
   },
-  motionTextOn: {
+  sliderRow: {
+    flexDirection: "row",
+    alignItems: "center",
+    gap: 8,
+    marginTop: 7
+  },
+  live: {
+    paddingHorizontal: 7,
+    paddingVertical: 3,
+    borderRadius: 6,
+    borderWidth: 1,
+    borderColor: _macOSDesignSystemColors.macOSColors.border.default,
+    backgroundColor: "rgba(38,38,42,0.8)"
+  },
+  liveOn: {
+    borderColor: _macOSDesignSystemColors.macOSColors.semantic.success + "55",
+    backgroundColor: _macOSDesignSystemColors.macOSColors.semantic.successBackground
+  },
+  liveText: {
+    fontSize: 9,
+    fontWeight: "700",
+    letterSpacing: 0.6,
+    color: _macOSDesignSystemColors.macOSColors.text.muted
+  },
+  liveTextOn: {
+    color: _macOSDesignSystemColors.macOSColors.semantic.success
+  },
+  playOn: {
+    borderColor: _macOSDesignSystemColors.macOSColors.semantic.info + "55",
+    backgroundColor: _macOSDesignSystemColors.macOSColors.semantic.infoBackground
+  },
+  playTextOn: {
     color: _macOSDesignSystemColors.macOSColors.semantic.info
+  },
+  track: {
+    flex: 1,
+    height: 24,
+    justifyContent: "center"
+  },
+  trackBar: {
+    height: 3,
+    borderRadius: 1.5,
+    backgroundColor: "rgba(120,130,150,0.35)"
+  },
+  thumb: {
+    position: "absolute",
+    top: (24 - THUMB) / 2,
+    width: THUMB,
+    height: THUMB,
+    borderRadius: THUMB / 2,
+    backgroundColor: _macOSDesignSystemColors.macOSColors.text.secondary,
+    borderWidth: 1,
+    borderColor: "rgba(255,255,255,0.5)"
+  },
+  thumbScrub: {
+    backgroundColor: _macOSDesignSystemColors.macOSColors.semantic.info
+  },
+  time: {
+    color: _macOSDesignSystemColors.macOSColors.text.secondary,
+    fontSize: 10,
+    fontVariant: ["tabular-nums"],
+    width: 32,
+    textAlign: "right"
   }
 });

package/lib/commonjs/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/commonjs/ui/backgrounds/backgroundStore.js

@@ -3,7 +3,7 @@
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
-exports.backgroundStore = void 0;
+exports.backgroundStore = exports.BACKGROUND_STORAGE_KEY = void 0;
 exports.useToolBackground = useToolBackground;
 var _react = require("react");
 var _devToolsStorageKeys = require("../../storage/devToolsStorageKeys.js");
@@ -19,7 +19,20 @@ var _registry = require("./registry.js");
  * choice the user already made.
  */
 
-const KEY = `${_devToolsStorageKeys.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.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). */
+const BACKGROUND_STORAGE_KEY = exports.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" && _registry.BACKGROUND_PRESETS.some(p => p.id === value);
 }
@@ -52,8 +65,10 @@ class BackgroundStore {
         const raw = await _persistentStorage.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".
@@ -64,8 +79,7 @@ class BackgroundStore {
   persist() {
     this.dirty = true;
     const payload = {
-      id: this.id,
-      motion: this.motion
+      id: this.id
     };
     void _persistentStorage.persistentStorage.setItem(KEY, JSON.stringify(payload)).catch(() => {});
   }