Stop sending a referrer, and keep CARTO on the fallback for now

The only referrer a browser can send is its origin, and for a Nabu Casa
instance that origin is a per-installation identifier. Sending it to a
third party on every tile request is not a trade we want to make, and it
turns out we do not have to: measured across several tiles and the
TileJSON, vector.openstreetmap.org serves a browser with no Referer at
all. So the vector layer sends none, and `transformRequest` goes with it.

The raster fallback is the half that did need one. OSM's raster tiles
block a refererless browser - with HTTP 200 and a PNG reading "Access
blocked", so nothing would even look broken - and a browser cannot set a
User-Agent instead. Rather than leak the origin for the devices least
able to choose, that path keeps CARTO: for them it is not a regression,
it is exactly what they see today, overlay and all.

Both halves are temporary. Once maps.home-assistant.io proxies with a
real application User-Agent, there is no referrer anywhere and the
fallback moves to OSM raster with it.

CARTO serves @2x, so retina tablets get sharp tiles at the same request
count, where Leaflet's `detectRetina` would have fetched a zoom deeper at
four times the requests.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: bramkragten

src/common/map/base-layer.ts

@@ -3,15 +3,11 @@ import type { Map as LeafletMap } from "leaflet";
 import type { StyleSpecification } from "maplibre-gl";
 import type { LeafletModuleType } from "../dom/setup-leaflet-map";
 
-// Only the raster fallback needs this: a Leaflet tile layer reads it, while
-// the vector layer takes its attribution from the source in the style, which
-// the TileJSON fills in. That is deliberately the better way around - the
-// credit follows whoever serves the tiles, and once that TileJSON is ours it
-// can be corrected remotely instead of in a release. Do not override it here:
-// upstream's currently omits "contributors", and that is theirs to fix or ours
-// to serve, not something to hardcode past.
-const OSM_ATTRIBUTION =
-  '&copy; <a href="https://www.openstreetmap.org/copyright">OpenStreetMap</a> contributors';
+// The vector layer sets no attribution of its own: it takes the credit from the
+// source in the style, which the TileJSON fills in. That is deliberately the
+// better way around - the credit follows whoever serves the tiles, and once that
+// TileJSON is ours it can be corrected remotely instead of in a release. Do not
+// hardcode one past it.
 
 // Shortbread vector tiles, served by the OpenStreetMap Foundation under
 // https://operations.osmfoundation.org/policies/vector/. Only their tile
@@ -22,12 +18,20 @@ const VECTOR_STYLES = {
   dark: "/static/map/dark.json",
 } as const;
 
-// Raster tiles for browsers that cannot run MapLibre. MapLibre draws raster
-// sources through WebGL too, so the fallback has to stay a Leaflet tile layer.
-const RASTER_TILE_URL = "https://tile.openstreetmap.org/{z}/{x}/{y}.png";
-// The raster tiles stop at 19, the vector tiles at 14 and are overzoomed. Both
-// keep rendering up to MAP_MAX_ZOOM.
-const RASTER_MAX_NATIVE_ZOOM = 19;
+// Raster tiles for browsers that cannot run MapLibre - it draws raster sources
+// through WebGL as well, so the fallback has to stay a Leaflet tile layer.
+//
+// This is temporary and it is CARTO, the basemap this change replaces, overlay
+// and all. OSM's raster tiles block a browser that sends no Referer, and the
+// only referrer a browser can send is its origin - which for a Nabu Casa
+// instance is a per-installation identifier. Rather than leak that, the devices
+// on this path keep exactly what they see today until maps.home-assistant.io can
+// proxy raster with an application User-Agent, at which point no referrer is
+// needed anywhere.
+const RASTER_TILE_URL = "https://basemaps.cartocdn.com/rastertiles/voyager";
+const CARTO_ATTRIBUTION =
+  '&copy; <a href="https://www.openstreetmap.org/copyright">OpenStreetMap</a>, ' +
+  '&copy; <a href="https://carto.com/attributions">CARTO</a>';
 
 // Browsers keep a limited number of live WebGL contexts - around 16 in Chrome -
 // and drop the oldest when a new one is created. A dashboard with more map
@@ -104,10 +108,11 @@ const createVectorLayer = async (
       // Renders CJK, kana and hangul with a font from the device, which is why
       // we only have to ship a tenth of the glyph set.
       localIdeographFontFamily: "sans-serif",
-      // The page sets a same-origin referrer policy, but the OSMF asks for a
-      // referrer to see which application their tiles are serving. Sending it
-      // for the tiles alone keeps it to the origin, never the page URL.
-      transformRequest: (url) => ({ url, referrerPolicy: "origin" }),
+      // No referrer is set for these: the vector endpoint serves them without
+      // one (measured), and the only referrer a browser can send is its origin,
+      // which identifies a Nabu Casa installation. Identifying Home Assistant
+      // properly is a job for maps.home-assistant.io, which can send a real
+      // application User-Agent.
     });
     // The plugin builds the MapLibre map in `onAdd`, so this is where a
     // missing WebGL context, a blocked worker or a rejected blob URL throws.
@@ -220,20 +225,17 @@ const createRasterLayer = (
   map: LeafletMap
 ): MapBaseLayer => {
   leaflet
-    .tileLayer(RASTER_TILE_URL, {
-      attribution: OSM_ATTRIBUTION,
-      maxNativeZoom: RASTER_MAX_NATIVE_ZOOM,
-      maxZoom: MAP_MAX_ZOOM,
-      // The tile images inherit the page's same-origin referrer policy, which
-      // sends nothing at all cross-origin. OSM's raster tile policy asks for a
-      // referrer, and being blocked would take out the fallback on exactly the
-      // devices that depend on it.
-      referrerPolicy: "origin",
-      // The devices that end up here are the old retina tablets, and OSM
-      // serves no @2x raster tiles, so sharp tiles have to come from loading a
-      // zoom level deeper at half the tile size.
-      detectRetina: true,
-    })
+    .tileLayer(
+      // The devices on this path are the old retina tablets. CARTO serves @2x,
+      // so they get sharp tiles for the same number of requests - Leaflet's
+      // `detectRetina` would instead fetch a zoom level deeper at four times
+      // the requests, which is only worth it against a source without @2x.
+      `${RASTER_TILE_URL}/{z}/{x}/{y}${leaflet.Browser.retina ? "@2x" : ""}.png`,
+      {
+        attribution: CARTO_ATTRIBUTION,
+        maxZoom: MAP_MAX_ZOOM,
+      }
+    )
     .addTo(map);
 
   return { setDarkMode: () => undefined };

test/common/map/base-layer.test.ts

@@ -26,8 +26,11 @@ const STYLE = {
 };
 
 const rasterLayer = { addTo: vi.fn() };
+// Kept as a local so tests can flip it: @types/leaflet has it readonly.
+const browser = { retina: false };
 const leaflet = {
   tileLayer: vi.fn(() => rasterLayer),
+  Browser: browser,
 } as unknown as LeafletModuleType;
 
 // `createVectorLayer` listens on both the MapLibre map and the Leaflet map.
@@ -81,18 +84,29 @@ describe("createBaseLayer", () => {
     expect(isRaster()).toBe(true);
     expect(maplibreGL).not.toHaveBeenCalled();
     expect(rasterLayer.addTo).toHaveBeenCalledWith(map);
-    // The page sends no referrer cross-origin, and OSM's raster tile policy
-    // asks for one. Being blocked would take out the fallback on exactly the
-    // devices that depend on it.
-    expect(vi.mocked(leaflet.tileLayer).mock.calls[0][1]).toMatchObject({
-      referrerPolicy: "origin",
-      // OSM serves no @2x raster tiles, and the devices that end up on the
-      // fallback are the old retina tablets.
-      detectRetina: true,
-      // The vector layer gets this from the style's source instead, so the
-      // raster layer is the only one that has to carry it itself.
-      attribution: expect.stringContaining("openstreetmap.org/copyright"),
-    });
+    const [url, options = {}] = vi.mocked(leaflet.tileLayer).mock.calls[0];
+    // No referrer: the only one a browser can send is its origin, which
+    // identifies a Nabu Casa installation. The fallback source is chosen so it
+    // does not need one.
+    expect(options).not.toHaveProperty("referrerPolicy");
+    // The vector layer takes its credit from the style's source instead, so the
+    // raster layer is the only one carrying attribution itself - and it credits
+    // both the data and whoever rendered it.
+    expect(options.attribution).toContain("openstreetmap.org/copyright");
+    expect(options.attribution).toContain("carto.com/attributions");
+    expect(url).toMatch(/\{z\}\/\{x\}\/\{y\}/);
+  });
+
+  // The devices on the fallback are the old retina tablets, and the source
+  // serves @2x, so they get sharp tiles without quadrupling the requests.
+  it("asks for @2x raster tiles on a retina screen", async () => {
+    const createBaseLayer = await setWebGL2(false);
+    browser.retina = true;
+
+    await createBaseLayer(leaflet, map, false);
+
+    expect(vi.mocked(leaflet.tileLayer).mock.calls[0][0]).toContain("@2x.png");
+    browser.retina = false;
   });
 
   it("uses vector tiles when WebGL2 is available", async () => {