leaflet-india-boundary 0.1.0

package/tools/build-india-boundary.mjs

@@ -0,0 +1,836 @@
+#!/usr/bin/env node
+/**
+ * Derives India's claimed boundary through Jammu & Kashmir, Ladakh and Aksai Chin
+ * from OpenStreetMap, instead of trusting a coordinate list pasted into an issue
+ * thread.
+ *
+ *   node tools/build-india-boundary.mjs                 # fetch, classify, report
+ *   node tools/build-india-boundary.mjs --cache         # reuse the last download
+ *   node tools/build-india-boundary.mjs --geojson out.json
+ *   node tools/build-india-boundary.mjs --retag         # re-check src/data.ts tags
+ *   node tools/build-india-boundary.mjs --retag --write # …and rewrite them
+ *
+ * WHY THIS EXISTS
+ * The coordinates in src/data.ts were copied from a comment on Leaflet/Leaflet#8943.
+ * They render correctly, but nobody can check them: we do not know who produced
+ * them or from what. This script replaces "trust the paste" with a query anyone can
+ * re-run and diff, against data that is ODbL-licensed and — because it is the same
+ * database the tiles are rendered from — matches the basemap's own geometry by
+ * construction.
+ *
+ * HOW IT WORKS
+ * India's claim is the *outer* edge of the union of the four regions that make up
+ * the disputed territory. That outer edge can be found without any geometry
+ * library, purely from way membership:
+ *
+ *   - a boundary way belonging to TWO of the four regions is internal — this is
+ *     exactly the Line of Control, and it drops out on its own.
+ *   - a way belonging to ONE is on the outer edge. Those are then classified by
+ *     which neighbour shares them:
+ *       shared with an Indian state       -> internal to India, drop
+ *       shared with China                 -> the LAC, i.e. control not claim, drop
+ *       otherwise (Pakistan, Afghanistan) -> India's claimed border, keep
+ *
+ * The dropped China stretch is then refilled from ways OSM tags `claimed_by=IN`
+ * (named "Indian claim line", "Indian claimed border" and similar).
+ *
+ * STATUS — READ BEFORE WIRING THE OUTPUT INTO AN APP
+ * The derivation is trustworthy for what it is used for (`--retag`, and the
+ * suppression geometry). Its full output is deliberately NOT shipped as the
+ * boundary, and the reasons are settled rather than open:
+ *
+ *   1. The open ends are not closeable. An earlier version of this note said they
+ *      needed "endpoint snapping with a tolerance". That was wrong, and measuring
+ *      is what showed it: the ends are 12, 21, 33 and 158 km apart. Snapping would
+ *      draw straight lines through the Karakoram. Four of the five stubborn ones sit
+ *      within 10 m of the Line of Actual Control — they are where the claim data OSM
+ *      holds runs out, and continuing means drawing China's line instead of India's.
+ *      Only upstream mapping fixes that, not geometry.
+ *   2. India's claim north of the Sino-Pakistan line — the Shaksgam Valley /
+ *      Trans-Karakoram Tract — is essentially absent from OSM. A query for
+ *      `claimed_by` ways in that bbox returns two. A pure-OSM derivation therefore
+ *      understates the northern claim, which is why the "hand" features in
+ *      src/data.ts are still hand-carried.
+ *   3. Where OSM *can* supply better geometry — the western arc facing Pakistan and
+ *      Afghanistan — it was measured and rejected on cost. Run `--merge` to
+ *      reproduce: it lifts the western arc from ~280 points to ~4700, and renders
+ *      indistinguishably from what ships. Mean deviation from the shipped line is
+ *      182 m, which is a fifth of a pixel at z10. The payload goes from 6 kB gzipped
+ *      to about 40 kB. Ten times the bytes for no visible change is a bad trade in a
+ *      browser package, so the shipped file stays at 689 points.
+ *
+ * The `--merge` investigation did pay for itself, though: it surfaced a real bug.
+ * 12 ways of Line of Control were being classified as India's claimed border,
+ * because the membership test cannot see them. See `isLineOfControl`.
+ *
+ * WHAT IS ALREADY USABLE
+ * `--retag` uses the derivation for the job it is actually good at: checking, for
+ * every feature in src/data.ts, whether OSM independently puts a boundary within
+ * a tolerance of it. That is what produced the `source` tags, and re-running it is
+ * how you find out whether upstream mapping has caught up.
+ */
+
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
+const DATA_TS = join(ROOT, "src/data.ts");
+const CACHE = join(tmpdir(), "india-boundary-osm.json");
+
+/**
+ * Overpass endpoint. Override with `--endpoint <url>` or `OVERPASS_URL`.
+ *
+ * This query asks for seven whole admin relations and every way in four of them,
+ * which is heavy enough that the main instance answers 504 Gateway Timeout
+ * whenever it is busy — not a fault in the query, just a queue. The mirrors below
+ * run the same software against the same data and are usually quieter:
+ *
+ *   https://overpass.kumi.systems/api/interpreter
+ *   https://overpass.private.coffee/api/interpreter
+ *
+ * Once a run succeeds, `--cache` reuses the download and you can stop asking.
+ */
+const OVERPASS = "https://overpass-api.de/api/interpreter";
+
+/** The four regions whose union is the territory India claims. */
+const CLAIM_REGIONS = {
+  1943188: "Jammu and Kashmir (India-administered)",
+  5515045: "Ladakh (India-administered)",
+  3780130: "Azad Kashmir (Pakistan-administered)",
+  357995: "Gilgit-Baltistan (Pakistan-administered)",
+};
+
+/** Neighbours used only to classify the outer edge, never drawn. */
+const CHINA = { 153310: "Xinjiang", 153292: "Xizang" };
+const INDIAN_STATES = {
+  364186: "Himachal Pradesh",
+  1942686: "Punjab",
+  9987086: "Uttarakhand",
+};
+
+/**
+ * Aksai Chin only. Do not widen this past roughly lat 36.2 / lon 80.6: it starts
+ * dragging in the Himachal–Tibet sector, which is a separate dispute and does not
+ * connect to this ring.
+ */
+const CLAIM_WAY_BBOX = [32.5, 76.0, 36.2, 80.6];
+
+/**
+ * Corroboration tolerance in metres, for `--retag`. Override with `--tolerance`.
+ *
+ * 10 km looks slack for a boundary check, and would be if the distances were spread
+ * evenly. They are not — measured against OSM's own derived line, the 67 shipped
+ * features fall into two clumps with a wide empty gap between them:
+ *
+ *   36 features   0.0 km – 5.1 km      (30 of them at 0.0: OSM's exact geometry)
+ *                 ~~~~ 3x gap, nothing in it ~~~~
+ *   31 features  14.3 km – 180.5 km    (OSM has no boundary there at all)
+ *
+ * So the classification is a fact about the data rather than a consequence of the
+ * threshold: every tolerance from about 6 km to 14 km sorts the features
+ * identically. 10 km sits in the middle of the gap, which makes it the least
+ * arbitrary number available. Run `--retag` to print the full distribution and
+ * confirm the gap is still there.
+ */
+const DEFAULT_TOLERANCE_M = 10000;
+
+const ids = (o) => Object.keys(o).join(",");
+
+const QUERY = `[out:json][timeout:250];
+rel(id:${ids(CLAIM_REGIONS)},${ids(CHINA)},${ids(INDIAN_STATES)})->.all;
+.all out body;
+rel(id:${ids(CLAIM_REGIONS)})->.claim;
+way(r.claim)->.cw;
+.cw out geom;
+way["claimed_by"](${CLAIM_WAY_BBOX.join(",")})->.cl;
+.cl out geom;`;
+
+async function fetchOsm(useCache, endpoint) {
+  if (useCache && existsSync(CACHE)) {
+    console.log(`using cached ${CACHE}`);
+    return JSON.parse(readFileSync(CACHE, "utf8"));
+  }
+  console.log(`querying ${endpoint} (this takes a while)…`);
+  // The User-Agent matters: Apache in front of Overpass answers 406 to any request
+  // that does not send one, and Node's fetch does not send one. The failure looks
+  // exactly like a query syntax error, so it is worth being explicit about. GET for
+  // the same reason — POST hits the same wall, and the query fits in a URL.
+  const res = await fetch(`${endpoint}?${new URLSearchParams({ data: QUERY })}`, {
+    headers: {
+      "User-Agent":
+        "leaflet-india-boundary (+https://github.com/lux-in-tenebris-lucet/leaflet-india-boundary)",
+      Accept: "application/json",
+    },
+  });
+  const text = await res.text();
+  if (res.status === 504 || res.status === 429) {
+    throw new Error(
+      `Overpass ${res.status} ${res.statusText}. The instance is busy or rate-limiting; ` +
+        `the query itself is fine. Try a mirror:\n` +
+        `  node tools/build-india-boundary.mjs --endpoint https://overpass.kumi.systems/api/interpreter`,
+    );
+  }
+  if (!res.ok) {
+    throw new Error(`Overpass ${res.status} ${res.statusText}\n${text.slice(0, 400)}`);
+  }
+  if (!text.startsWith("{")) {
+    throw new Error(`Overpass returned non-JSON (rate limited?): ${text.slice(0, 300)}`);
+  }
+  writeFileSync(CACHE, text);
+  return JSON.parse(text);
+}
+
+/**
+ * Is this way the Line of Control, according to OSM's own tags?
+ *
+ * The membership test below — a way in two of the four claim regions is internal —
+ * finds most of the LoC, but it leaks. The southern stretch, the "working boundary"
+ * running east from near Jammu, has Pakistani *Punjab province* on the far side
+ * rather than Azad Kashmir. So it belongs to only one of the four regions, never
+ * trips the shared-by-two test, and used to come out the other end classified as
+ * India's claimed border: 11 ways and 2228 points of Line of Control, drawn as the
+ * claim and missing from the suppression mask.
+ *
+ * OSM tags it explicitly, so ask instead of inferring. Every leaked way carries
+ * `disputed=yes` with `disputed_by=IN;PK` and `name:en=Line of Control`, while every
+ * way we legitimately keep here — the Durand Line facing Afghanistan, and Azad
+ * Kashmir's and Gilgit-Baltistan's boundaries with Pakistan proper — has no
+ * `disputed` tag at all. Some of those carry `disputed_by=IN` on its own, which means
+ * India disputes the administration rather than that the line is the LoC, so testing
+ * `disputed_by` alone would throw away most of the claim edge.
+ *
+ * `claimed_by=IN` still wins: a way India's claim line runs along is kept even if
+ * someone has also marked it disputed.
+ */
+function isLineOfControl(way) {
+  const t = way?.tags ?? {};
+  if (t.claimed_by === "IN") return false;
+  if (t.disputed !== "yes") return false;
+  // Must name Pakistan. This test runs before the China test, and `disputed=yes`
+  // alone also matches the India-China LAC — which would still be masked, but
+  // labelled "loc" when it is the LAC, making the suppression data lie about which
+  // line is which. Let those fall through to the China branch.
+  return /\bPK\b/.test(t.disputed_by ?? "");
+}
+
+function classify(osm) {
+  const relations = new Map();
+  const ways = new Map();
+  for (const el of osm.elements) {
+    if (el.type === "relation") relations.set(el.id, el);
+    else if (el.type === "way") ways.set(el.id, el);
+  }
+
+  const membersOf = (id) =>
+    new Set(
+      (relations.get(id)?.members ?? []).filter((m) => m.type === "way").map((m) => m.ref),
+    );
+
+  // How many of the four claim regions each way belongs to.
+  const shareCount = new Map();
+  for (const id of Object.keys(CLAIM_REGIONS)) {
+    for (const w of membersOf(Number(id))) {
+      shareCount.set(w, (shareCount.get(w) ?? 0) + 1);
+    }
+  }
+
+  const union = (obj) =>
+    new Set(Object.keys(obj).flatMap((id) => [...membersOf(Number(id))]));
+  const chinaWays = union(CHINA);
+  const stateWays = union(INDIAN_STATES);
+
+  const internal = [];
+  const taggedLoc = [];
+  const droppedChina = [];
+  const droppedState = [];
+  const keep = [];
+  for (const [w, n] of shareCount) {
+    if (n >= 2) internal.push(w);
+    // An explicit claimed_by=IN tag outranks the China test. Some of these ways are
+    // members of Xinjiang's relation as well, and dropping them as "shared with
+    // China" would throw away the very claim line we are trying to keep.
+    else if (ways.get(w)?.tags?.claimed_by === "IN") keep.push(w);
+    // China before the tag test, deliberately. The far-northern Sino-Pakistan line is
+    // tagged `disputed_by=IN;PK` too — Pakistan is a party to it — so testing tags
+    // first would label a stretch of the LAC as Line of Control. Both end up masked
+    // either way, but the labels are what a maintainer reads, so they should be true.
+    else if (chinaWays.has(w)) droppedChina.push(w);
+    // What remains: the membership test above misses the southern LoC. See
+    // isLineOfControl for why.
+    else if (isLineOfControl(ways.get(w))) taggedLoc.push(w);
+    else if (stateWays.has(w)) droppedState.push(w);
+    else keep.push(w);
+  }
+
+  // `claimed_by=IN` ways refill the dropped China stretch. They arrive in the same
+  // response but are not members of any claim region, so they are absent from
+  // shareCount.
+  const claimWays = [...ways.values()].filter(
+    (w) => w.tags?.claimed_by === "IN" && !shareCount.has(w.id),
+  );
+
+  return { ways, internal, taggedLoc, droppedChina, droppedState, keep, claimWays };
+}
+
+/**
+ * Dangling endpoints are where the assembled ring fails to close. OSM ways share
+ * nodes at junctions, so identical coordinates mean a real join.
+ */
+function findGaps(segments) {
+  const seen = new Map();
+  const bump = (p) => {
+    const k = `${p[0]},${p[1]}`;
+    seen.set(k, (seen.get(k) ?? 0) + 1);
+  };
+  for (const s of segments) {
+    bump(s[0]);
+    bump(s[s.length - 1]);
+  }
+  return [...seen.entries()]
+    .filter(([, n]) => n === 1)
+    .map(([k]) => k.split(",").map(Number));
+}
+
+/* ------------------------------------------------------------------ *
+ * Corroboration: how far is each shipped feature from OSM's own line?
+ * ------------------------------------------------------------------ */
+
+const R = 6371008.8;
+const RAD = Math.PI / 180;
+/**
+ * Local equirectangular projection. The whole region sits between roughly 32°N and
+ * 37°N, so one cosine taken at the middle is accurate to well under a percent
+ * here — far tighter than a kilometre-scale tolerance needs, and it keeps this
+ * script free of a projection dependency.
+ */
+const LAT0_COS = Math.cos(34.5 * RAD);
+const toXY = ([lon, lat]) => [lon * RAD * LAT0_COS * R, lat * RAD * R];
+
+function pointToSegmentM(p, a, b) {
+  const [px, py] = p;
+  const [ax, ay] = a;
+  const [bx, by] = b;
+  const dx = bx - ax;
+  const dy = by - ay;
+  const len2 = dx * dx + dy * dy;
+  let t = len2 === 0 ? 0 : ((px - ax) * dx + (py - ay) * dy) / len2;
+  t = Math.max(0, Math.min(1, t));
+  const cx = ax + t * dx;
+  const cy = ay + t * dy;
+  return Math.hypot(px - cx, py - cy);
+}
+
+/** Min distance in metres from a point to any of the reference polylines. */
+function distanceToLines(point, lines) {
+  let best = Infinity;
+  for (const line of lines) {
+    for (let i = 1; i < line.length; i += 1) {
+      const d = pointToSegmentM(point, line[i - 1], line[i]);
+      if (d < best) best = d;
+      if (best === 0) return 0;
+    }
+  }
+  return best;
+}
+
+/**
+ * Reads the feature objects out of src/data.ts.
+ *
+ * data.ts is generated one feature per line precisely so this stays a line-wise
+ * operation: no TypeScript parser, and rewriting the tags cannot disturb the long
+ * provenance comment above them.
+ */
+const FEATURE_LINE = /^ {2}(\{"type":"Feature".*\}),$/;
+
+function readShippedFeatures() {
+  const text = readFileSync(DATA_TS, "utf8");
+  const lines = text.split("\n");
+  const features = [];
+  lines.forEach((line, i) => {
+    const m = FEATURE_LINE.exec(line);
+    if (m) features.push({ index: i, feature: JSON.parse(m[1]) });
+  });
+  if (!features.length) {
+    throw new Error(
+      `found no feature lines in ${DATA_TS} — has its formatting changed? ` +
+        `each feature must be a single line of the form '  {"type":"Feature",…},'`,
+    );
+  }
+  return { lines, features };
+}
+
+function retag(osmLines, tolerance, write) {
+  const { lines, features } = readShippedFeatures();
+
+  const results = features.map(({ index, feature }) => {
+    // Worst vertex, not the average: a feature counts as corroborated only if OSM
+    // backs up the whole of it. Averaging would let a segment that wanders off for
+    // a third of its length still pass.
+    let worst = 0;
+    for (const c of feature.geometry.coordinates) {
+      const d = distanceToLines(toXY(c), osmLines);
+      if (d > worst) worst = d;
+    }
+    return { index, feature, worst, source: worst <= tolerance ? "osm" : "hand" };
+  });
+
+  const was = { osm: 0, hand: 0 };
+  const now = { osm: 0, hand: 0 };
+  const flipped = [];
+  for (const r of results) {
+    was[r.feature.properties.source] += 1;
+    now[r.source] += 1;
+    if (r.source !== r.feature.properties.source) flipped.push(r);
+  }
+
+  console.log(`
+corroboration check  (tolerance ${tolerance} m, worst vertex per feature)
+  shipped tags   ${was.osm} osm / ${was.hand} hand
+  recomputed     ${now.osm} osm / ${now.hand} hand
+  disagreements  ${flipped.length}`);
+
+  for (const r of flipped) {
+    console.log(
+      `    ${r.feature.properties.source} -> ${r.source}  ` +
+        `worst ${(r.worst / 1000).toFixed(1)} km  ` +
+        `at lon=${r.feature.geometry.coordinates[0][0].toFixed(3)} ` +
+        `lat=${r.feature.geometry.coordinates[0][1].toFixed(3)}`,
+    );
+  }
+
+  // The distances either side of the cutoff. If features cluster just under the
+  // tolerance, the split is an artefact of the threshold rather than a fact about
+  // OSM — so print the lot and let the reader see which it is.
+  const sorted = [...results].sort((a, b) => a.worst - b.worst);
+  console.log("\n  worst-vertex distance, every feature, ascending (km)");
+  const row = sorted.map((r) => (r.worst / 1000).toFixed(1));
+  for (let i = 0; i < row.length; i += 12) {
+    console.log(`    ${row.slice(i, i + 12).join("  ")}`);
+  }
+
+  // How far could the tolerance move before a single tag changed? That is the band
+  // between the furthest feature we called corroborated and the nearest feature we
+  // did not — and it is the number that says whether these tags mean anything. A
+  // wide band means the two groups are genuinely separate and the threshold is
+  // just picking a point in the empty space between them. A narrow one means the
+  // split is an artefact of the threshold.
+  const worstOf = (source) => results.filter((r) => r.source === source).map((r) => r.worst);
+  const osmMax = Math.max(...worstOf("osm"), 0);
+  const handWorst = worstOf("hand");
+  const handMin = handWorst.length ? Math.min(...handWorst) : Infinity;
+
+  if (Number.isFinite(handMin)) {
+    const ratio = osmMax > 0 ? handMin / osmMax : Infinity;
+    console.log(
+      `\n  the cutoff could sit anywhere in ${(osmMax / 1000).toFixed(1)} km – ${(handMin / 1000).toFixed(1)} km ` +
+        `without changing a tag`,
+    );
+    console.log(
+      ratio >= 2
+        ? `  furthest corroborated feature is ${ratio.toFixed(1)}x closer than the nearest\n` +
+            `  uncorroborated one, so the split is a fact about the data rather than about\n` +
+            `  the ${tolerance} m threshold`
+        : `  WARNING: only ${ratio.toFixed(1)}x between the two groups. They are not cleanly\n` +
+            `  separated, so this split depends on the ${tolerance} m threshold and should not\n` +
+            `  be described as a property of the data.`,
+    );
+  }
+
+  if (!write) {
+    if (flipped.length) console.log("\n  pass --write to apply these to src/data.ts");
+    return;
+  }
+  if (!flipped.length) {
+    console.log("\n  nothing to write: src/data.ts already agrees");
+    return;
+  }
+  for (const r of results) {
+    const updated = { ...r.feature, properties: { ...r.feature.properties, source: r.source } };
+    lines[r.index] = `  ${JSON.stringify(updated)},`;
+  }
+  writeFileSync(DATA_TS, lines.join("\n"));
+  console.log(`\n  wrote ${DATA_TS} (${flipped.length} tag(s) changed)`);
+  console.log("  remember to update the counts in the header comment if they moved");
+}
+
+/* ------------------------------------------------------------------ *
+ * Merge: upgrade the western arc to OSM's detail, keep the rest
+ * ------------------------------------------------------------------ */
+
+/**
+ * Replaces the stretches of the shipped line that OSM can supply at higher detail,
+ * and leaves the rest alone.
+ *
+ * WHY THIS IS NOT "CLOSE THE GAPS AND SHIP THE DERIVATION"
+ *
+ * The STATUS block above used to say the derivation needed endpoint snapping before
+ * it could be rendered. That was wrong about the cause, and measuring it is what
+ * showed why. The open ends are 12, 21, 33 and 158 km apart. Snapping across those
+ * would draw straight lines through the Karakoram — far worse than the shorter line
+ * that at least follows the right alignment.
+ *
+ * They are not gaps to be closed. Four of the five stubborn ones sit within 10 m of
+ * the Line of Actual Control, which is to say they are exactly where the claim data
+ * OSM holds runs out and continuing would mean drawing China's line instead of
+ * India's. No amount of snapping fixes that; only upstream mapping does.
+ *
+ * What *is* available splits cleanly in two:
+ *
+ *   - The western and northern arc, facing Pakistan and Afghanistan, is 69 ways and
+ *     ~6900 points forming a chain with two open ends. It is simultaneously India's
+ *     claim and a real administered boundary, so OSM maps it properly, and it can
+ *     replace the shipped geometry outright at roughly ten times the detail.
+ *   - The eastern arc — the Aksai Chin claim line and the Shaksgam claim — has 614
+ *     points of fragmentary `claimed_by=IN` data with eight open ends. It has to stay
+ *     hand-carried.
+ *
+ * HOW A FEATURE IS DECIDED
+ *
+ * By distance to the region-derived chain, not by its `source` tag. That distinction
+ * matters: a shipped feature in eastern Ladakh can be tagged "osm" because OSM has a
+ * boundary within the corroboration tolerance — but that boundary is the LAC, which
+ * is the line we exist to replace. Measuring against the region-derived chain instead
+ * separates "OSM has this same line, better" from "OSM has a different line nearby".
+ */
+function merge(regionSegs, shipped, toleranceM, out) {
+  const chain = regionSegs.map((s) => s.map(toXY));
+
+  const decided = shipped.map((f) => {
+    let worst = 0;
+    for (const c of f.geometry.coordinates) {
+      const d = distanceToLines(toXY(c), chain);
+      if (d > worst) worst = d;
+    }
+    return { feature: f, worst, superseded: worst <= toleranceM };
+  });
+
+  const superseded = decided.filter((d) => d.superseded);
+  const kept = decided.filter((d) => !d.superseded);
+  const pointsOf = (fs) =>
+    fs.reduce((n, d) => n + d.feature.geometry.coordinates.length, 0);
+  const chainPoints = regionSegs.reduce((n, s) => n + s.length, 0);
+
+  const features = [
+    ...regionSegs.map((coords) => ({
+      type: "Feature",
+      geometry: { type: "LineString", coordinates: coords },
+      properties: { source: "osm" },
+    })),
+    ...kept.map((d) => d.feature),
+  ];
+  const total = features.reduce((n, f) => n + f.geometry.coordinates.length, 0);
+
+  // Does the merged ring still join up? The derived chain's two ends have to meet
+  // whatever the kept features leave open, or the line breaks somewhere new.
+  const ends = new Map();
+  for (const f of features) {
+    const cs = f.geometry.coordinates;
+    for (const p of [cs[0], cs[cs.length - 1]]) {
+      const key = `${p[0].toFixed(4)},${p[1].toFixed(4)}`;
+      ends.set(key, (ends.get(key) ?? 0) + 1);
+    }
+  }
+  const open = [...ends.entries()]
+    .filter(([, n]) => n === 1)
+    .map(([k]) => k.split(",").map(Number));
+
+  // How far is each open end from the nearest other open end? Small means a joinable
+  // seam; large means a real break in the depiction.
+  const openPairs = open.map((a) => {
+    let best = Infinity;
+    for (const b of open) {
+      if (a === b) continue;
+      const d = Math.hypot(...toXY(a).map((v, i) => v - toXY(b)[i]));
+      if (d < best) best = d;
+    }
+    return { a, best };
+  });
+
+  console.log(`
+merge  (supersede threshold ${toleranceM} m)
+  shipped features superseded by OSM detail   ${superseded.length}  (${pointsOf(superseded)} points)
+  shipped features kept as they are           ${kept.length}  (${pointsOf(kept)} points)
+  region-derived chain added                  ${regionSegs.length} ways  (${chainPoints} points)
+
+  merged total    ${features.length} features, ${total} points   (was 67 / 689)
+
+  open ends       ${open.length}`);
+  for (const { a, best } of openPairs.sort((x, y) => x.best - y.best)) {
+    const far = best > 3000;
+    console.log(
+      `    lon=${a[0].toFixed(4)} lat=${a[1].toFixed(4)}  nearest other open end ` +
+        `${(best / 1000).toFixed(2)} km${far ? "   <-- too far to be a seam" : ""}`,
+    );
+  }
+  console.log(`
+  kept features, by how far they sit from the derived chain:`);
+  for (const d of kept.sort((x, y) => x.worst - y.worst).slice(0, 8)) {
+    console.log(
+      `    ${(d.worst / 1000).toFixed(1).padStart(6)} km  ${d.feature.properties.source}  ` +
+        `starting lon=${d.feature.geometry.coordinates[0][0].toFixed(3)} ` +
+        `lat=${d.feature.geometry.coordinates[0][1].toFixed(3)}`,
+    );
+  }
+
+  if (out) {
+    writeFileSync(
+      out,
+      `${JSON.stringify({ type: "FeatureCollection", features })}\n`,
+    );
+    console.log(`\n  wrote ${out} — render it before trusting it`);
+  }
+  return features;
+}
+
+/* ------------------------------------------------------------------ *
+ * Suppression geometry: the lines the basemap draws that we want gone
+ * ------------------------------------------------------------------ */
+
+/**
+ * Douglas-Peucker, with the tolerance in metres via the projection above.
+ *
+ * The suppression mask is a ribbon a few pixels wide, so carrying OSM's full
+ * node density into the browser is pointless: what matters is that the polyline
+ * stays inside its own ribbon. See `--simplify` for how the tolerance relates to
+ * pixels per zoom.
+ */
+function simplify(points, toleranceM) {
+  if (points.length < 3) return points;
+  const xy = points.map(toXY);
+  const keep = new Uint8Array(points.length);
+  keep[0] = keep[points.length - 1] = 1;
+
+  const stack = [[0, points.length - 1]];
+  while (stack.length) {
+    const [first, last] = stack.pop();
+    let worst = -1;
+    let worstIdx = -1;
+    for (let i = first + 1; i < last; i += 1) {
+      const d = pointToSegmentM(xy[i], xy[first], xy[last]);
+      if (d > worst) {
+        worst = d;
+        worstIdx = i;
+      }
+    }
+    if (worst > toleranceM) {
+      keep[worstIdx] = 1;
+      stack.push([first, worstIdx], [worstIdx, last]);
+    }
+  }
+  return points.filter((_, i) => keep[i]);
+}
+
+/** Round to 5 decimal places — about 1.1 m here, well under any useful ribbon. */
+const round5 = ([lon, lat]) => [
+  Math.round(lon * 1e5) / 1e5,
+  Math.round(lat * 1e5) / 1e5,
+];
+
+function dumpSuppression(ways, internal, droppedChina, toleranceM, out) {
+  const lines = [
+    ...internal.map((id) => ["loc", ways.get(id)]),
+    ...droppedChina.map((id) => ["lac", ways.get(id)]),
+  ]
+    .filter(([, w]) => (w?.geometry?.length ?? 0) >= 2)
+    .map(([line, w]) => [line, w.geometry.map((p) => [p.lon, p.lat])]);
+
+  const before = lines.reduce((n, [, c]) => n + c.length, 0);
+  const features = lines.map(([line, coords]) => ({
+    type: "Feature",
+    geometry: {
+      type: "LineString",
+      coordinates: simplify(coords, toleranceM).map(round5),
+    },
+    properties: { line },
+  }));
+  const after = features.reduce((n, f) => n + f.geometry.coordinates.length, 0);
+
+  let west = Infinity;
+  let south = Infinity;
+  let east = -Infinity;
+  let north = -Infinity;
+  for (const f of features) {
+    for (const [lon, lat] of f.geometry.coordinates) {
+      if (lon < west) west = lon;
+      if (lon > east) east = lon;
+      if (lat < south) south = lat;
+      if (lat > north) north = lat;
+    }
+  }
+
+  const counts = features.reduce((acc, f) => {
+    acc[f.properties.line] = (acc[f.properties.line] ?? 0) + 1;
+    return acc;
+  }, {});
+
+  const header = `import type { FeatureCollection, LineString } from "geojson";
+
+/**
+ * The two lines a standard OSM basemap draws through this region that India's
+ * official depiction does not: the Line of Control and the Line of Actual Control.
+ *
+ * GENERATED — do not edit by hand. Regenerate with:
+ *   node tools/build-india-boundary.mjs --dump-suppression src/suppressionData.ts
+ *
+ * This is the *complement* of INDIA_BOUNDARY, and it comes free with deriving it.
+ * The derivation in this script works by discarding ways: a boundary way in two of
+ * the four claim regions is internal, which is exactly the Line of Control, and a
+ * way shared with China is the Line of Actual Control — control rather than claim.
+ * Both are thrown away to leave India's claimed outer edge. Kept instead, they are
+ * precisely the geometry needed to mask those lines out of a raster tile, in the
+ * same coordinate system the tiles were rendered from.
+ *
+ *   "loc" (${counts.loc ?? 0} features) — the Line of Control, India/Pakistan.
+ *   "lac" (${counts.lac ?? 0} features) — the Line of Actual Control, India/China.
+ *
+ * Simplified with Douglas-Peucker at ${toleranceM} m, taking ${before} OSM nodes down to
+ * ${after}. At latitude ~34.5 one pixel is about 2015 m at z6, 126 m at z10, 31 m at
+ * z12 and 8 m at z14, so this stays comfortably sub-pixel to z12 and within a couple
+ * of pixels at z14 — far inside the mask ribbon at any of them.
+ *
+ * Coordinates are [lon, lat], WGS 84, rounded to 5 decimal places (~1.1 m).
+ */
+export type SuppressionLine = "loc" | "lac";
+
+export interface SuppressionProperties {
+  line: SuppressionLine;
+}
+
+/** [west, south, east, north] — lets a tile layer skip unaffected tiles entirely. */
+export const SUPPRESSION_BBOX: readonly [number, number, number, number] = [
+  ${west}, ${south}, ${east}, ${north},
+];
+
+export const INDIA_BOUNDARY_SUPPRESSION: FeatureCollection<
+  LineString,
+  SuppressionProperties
+> = {
+  type: "FeatureCollection",
+  features: [
+`;
+
+  writeFileSync(
+    out,
+    `${header}${features.map((f) => `  ${JSON.stringify(f)},`).join("\n")}\n  ],\n};\n`,
+  );
+  console.log(`
+suppression geometry
+  LoC features   ${counts.loc ?? 0}
+  LAC features   ${counts.lac ?? 0}
+  points         ${before} -> ${after}  (Douglas-Peucker at ${toleranceM} m)
+  bbox           ${west.toFixed(4)}, ${south.toFixed(4)}, ${east.toFixed(4)}, ${north.toFixed(4)}
+  wrote          ${out}`);
+}
+
+/* ------------------------------------------------------------------ *
+ * main
+ * ------------------------------------------------------------------ */
+
+const args = process.argv.slice(2);
+const flagValue = (name) => {
+  const i = args.indexOf(name);
+  return i >= 0 ? args[i + 1] : undefined;
+};
+const tolerance = Number(flagValue("--tolerance") ?? DEFAULT_TOLERANCE_M);
+if (!Number.isFinite(tolerance) || tolerance <= 0) {
+  throw new Error(`--tolerance must be a positive number of metres, got ${tolerance}`);
+}
+
+const endpoint = flagValue("--endpoint") ?? process.env.OVERPASS_URL ?? OVERPASS;
+const osm = await fetchOsm(args.includes("--cache"), endpoint);
+const { ways, internal, taggedLoc, droppedChina, droppedState, keep, claimWays } =
+  classify(osm);
+
+const coords = (w) => w.geometry.map((p) => [p.lon, p.lat]);
+const segments = [...keep.map((id) => coords(ways.get(id))), ...claimWays.map(coords)];
+const points = segments.reduce((n, s) => n + s.length, 0);
+
+// Not every open end is a defect. Where the ring meets a boundary we dropped as
+// internal to India, the line is *supposed* to stop: past that point the border is
+// undisputed and the basemap already draws it correctly. Those endpoints are
+// termini, and flagging them as gaps would send someone chasing nothing.
+const indiaEdge = new Set(
+  droppedState.flatMap((id) => coords(ways.get(id)).map(([lon, lat]) => `${lon},${lat}`)),
+);
+const allGaps = findGaps(segments);
+const termini = allGaps.filter(([lon, lat]) => indiaEdge.has(`${lon},${lat}`));
+const gaps = allGaps.filter(([lon, lat]) => !indiaEdge.has(`${lon},${lat}`));
+
+console.log(`
+region assembly
+  ways across the four regions      ${internal.length + taggedLoc.length + droppedChina.length + droppedState.length + keep.length}
+  internal (the Line of Control)    ${internal.length}   dropped
+  LoC by tag, missed by membership   ${taggedLoc.length}   dropped, see isLineOfControl
+  shared with China (the LAC)       ${droppedChina.length}   dropped, refilled below
+  shared with Indian states         ${droppedState.length}   dropped, internal to India
+  India's claimed outer edge        ${keep.length}   kept
+  claimed_by=IN refill ways         ${claimWays.length}   kept
+
+result
+  segments  ${segments.length}
+  points    ${points}   (src/data.ts ships 689)
+
+open ends
+  termini at India's undisputed border  ${termini.length}   expected, not defects
+  real gaps                            ${gaps.length}${gaps.length ? "   <-- NOT yet safe to render" : "   ring closes"}`);
+for (const [lon, lat] of gaps.slice(0, 20)) {
+  console.log(`    lon=${lon.toFixed(4)} lat=${lat.toFixed(4)}`);
+}
+if (gaps.length) {
+  console.log(`
+  Rendering this as-is draws a broken border. See STATUS in this file's header: the
+  refilled China sector needs endpoint snapping, and India's claim north of the
+  Sino-Pakistan line (Shaksgam / Trans-Karakoram) is not in OSM to begin with.
+  Until both are resolved, src/data.ts stays as it is — a continuous line beats a
+  more precise broken one.`);
+}
+
+if (args.includes("--retag")) {
+  retag(
+    segments.map((s) => s.map(toXY)),
+    tolerance,
+    args.includes("--write"),
+  );
+}
+
+if (args.includes("--merge")) {
+  // Only the region-derived ways: the claimed_by=IN refills are fragmentary and sit
+  // on top of the eastern arc we are keeping, so adding them would draw two lines.
+  const regionSegs = keep
+    .filter((id) => ways.get(id)?.tags?.claimed_by !== "IN")
+    .map((id) => coords(ways.get(id)));
+  const { features: shipped } = readShippedFeatures();
+  merge(
+    regionSegs,
+    shipped.map((s) => s.feature),
+    Number(flagValue("--supersede") ?? 6000),
+    flagValue("--merge"),
+  );
+}
+
+const dump = flagValue("--dump-suppression");
+if (args.includes("--dump-suppression") && dump) {
+  dumpSuppression(
+    ways,
+    [...internal, ...taggedLoc],
+    droppedChina,
+    Number(flagValue("--simplify") ?? 15),
+    dump,
+  );
+}
+
+const out = flagValue("--geojson");
+if (args.includes("--geojson") && out) {
+  const fc = {
+    type: "FeatureCollection",
+    features: segments.map((c) => ({
+      type: "Feature",
+      geometry: { type: "LineString", coordinates: c },
+      properties: {},
+    })),
+  };
+  writeFileSync(out, JSON.stringify(fc));
+  console.log(`\nwrote ${out}`);
+}