From f67888be00327c45bb2f0a651979ea9eb77489f4 Mon Sep 17 00:00:00 2001
From: Rudy Celekli <rudy@gradiahq.com>
Date: Mon, 12 Oct 2026 11:12:01 -0400
Subject: [PATCH] docs: address review scope and feature placement for #1032

---
 CHANGELOG.md                                  |  3 ++
 docs/CURRENT-STATE.md                         |  9 +++---
 .../street-level-unique-tiles.test.mjs        | 29 ++++++++++++-------
 3 files changed, 25 insertions(+), 16 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 0814f7e7c..1d76a1963 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -17,6 +17,9 @@
 
 - Street Level requests count each tile once when dateline bounds overlap at coarse zoom levels.
 
+- Street Level counts unique tiles before ranking so overlapping dateline halves
+  in polar views do not waste slots in the 16-tile overview budget.
+
 - Treat explicitly current, complete empty vessel coverage as a successful update,
   clearing obsolete contacts while retaining stale or incomplete snapshots.
 
diff --git a/docs/CURRENT-STATE.md b/docs/CURRENT-STATE.md
index d0014227f..c2291829e 100644
--- a/docs/CURRENT-STATE.md
+++ b/docs/CURRENT-STATE.md
@@ -3122,6 +3122,10 @@ sequence lines below 60 km; the proxy strips the unused `image` layer from z14
 tiles (12 MB → ~80 KB) and shares one upstream fetch between concurrent
 requests for a tile.
 
+Mapillary coverage ranks unique tile addresses before applying the 16-tile
+overview budget. Overlapping dateline halves in a polar view therefore do not
+waste overview slots on the same tile; loading already skips duplicate keys.
+
 On Google 3D (`photoreal`) at street zoom (in below 1,400 m above ground, out
 above 1,800 m) the surface mode switches from `draped` to `terrain`: draped
 lines land on roofs and tree tops, so `groundCast.js` instead places lines,
@@ -5310,8 +5314,3 @@ datacenters, dams and the Nepal locator retain that shared credit while displaye
 
 Military fragments stitch by source identity. Different mapped parcels merge only
 when their footprints touch or contain one another, never across a seam tolerance gap.
-
-
-### fix(street-level): deduplicate overlapping dateline tile halves
-
-Deduplicate tile addresses before ranking, truncating and reporting total coverage. Dateline ordering and the existing focus policy remain in control.
diff --git a/src/layers/streetLevel/street-level-unique-tiles.test.mjs b/src/layers/streetLevel/street-level-unique-tiles.test.mjs
index f96f0b892..224de523b 100644
--- a/src/layers/streetLevel/street-level-unique-tiles.test.mjs
+++ b/src/layers/streetLevel/street-level-unique-tiles.test.mjs
@@ -1,15 +1,22 @@
 import test from 'node:test';
 import assert from 'node:assert/strict';
 import { tilesForBbox } from './tileMath.js';
-test('coarse dateline coverage counts each tile exactly once', () => {
-  for (const z of [0, 1, 2]) {
-    const result = tilesForBbox([170, -1, -170, 1], z);
-    const keys = result.tiles.map((t) => `${t.x}/${t.y}/${t.z}`);
-    assert.equal(new Set(keys).size, keys.length);
-    assert.equal(result.total, keys.length);
-    const limited = tilesForBbox([170, -1, -170, 1], z, { limit: 1 });
-    assert.equal(limited.total, keys.length);
-    assert.equal(limited.truncated, keys.length > 1);
-    assert.equal(limited.tiles.length, 1);
-  }
+
+test('reachable polar dateline coverage ranks 24 distinct tiles before overview truncation', () => {
+  // coverage uses the actual view bbox above zoom 1; polar views can wrap.
+  const bbox = [-10, 60, -20, 85];
+  const result = tilesForBbox(bbox, 3);
+  const keys = result.tiles.map((tile) => `${tile.x}/${tile.y}/${tile.z}`);
+  assert.equal(keys.length, 24);
+  assert.equal(new Set(keys).size, 24);
+  assert.equal(result.total, 24);
+  assert.equal(result.truncated, false);
+  const overview = tilesForBbox(bbox, 3, { limit: 16 });
+  assert.equal(overview.total, 24);
+  assert.equal(overview.tiles.length, 16);
+  assert.equal(
+    new Set(overview.tiles.map((tile) => `${tile.x}/${tile.y}/${tile.z}`)).size,
+    16,
+  );
+  assert.equal(overview.truncated, true);
 });