Switch map to sub-national regions (v0.12.0)

Part of #16

shared/protocol.ts

@@ -57,20 +57,41 @@ export interface RegionOwner {
 export type RegionMap = Record<string, RegionOwner>;
 
 /**
- * Look up the owner record for a map region from the authoritative RegionMap by
- * its ISO_A3 code. Returns `undefined` for an empty/missing code or an unowned
- * region. Pure + shared: the client resolves a clicked or hovered map feature by
- * first reading the feature's stable ISO_A3 code (stored in `properties.regionId`
- * by the client when it repacks the source — see WorldMap) and then calling this.
+ * Look up the owner record from the authoritative RegionMap by a RegionMap key.
+ * The RegionMap is keyed by the **parent country's** ISO_A3 code (ownership and
+ * the LLM stay at country granularity — see #16), so `key` is a country code such
+ * as `DEU`, never a sub-region id such as `DEU-03`. Returns `undefined` for an
+ * empty/missing key or an unowned country.
  *
- * The code must NOT be taken from the feature's top-level `id`: MapLibre repacks
- * a GeoJSON source's `id` (an ISO_A3 string) into a numeric index when it stores
- * the source, so at click/hover time `feature.id` is a number, never the ISO_A3
- * — resolving from it is exactly the "no owner" bug (#6).
+ * Pure + shared: the primitive "key → owner" lookup. The *map feature → owner*
+ * resolution (deciding which key to pass) lives in {@link mapFeatureOwner} below,
+ * which reads the feature's `properties.parent` — never the repacked top-level
+ * `id` (MapLibre turns it into a numeric index, the "no owner" bug #6) and never
+ * the sub-region id.
  */
-export function regionOwner(regions: RegionMap, isoA3: string | null | undefined): RegionOwner | undefined {
-  if (!isoA3) return undefined;
-  return regions[isoA3];
+export function regionOwner(regions: RegionMap, key: string | null | undefined): RegionOwner | undefined {
+  if (!key) return undefined;
+  return regions[key];
+}
+
+/**
+ * Resolve the owning-nation record for a **rendered map feature** from the
+ * authoritative RegionMap. The choropleth renders sub-national regions, but the
+ * RegionMap is keyed by the *parent country's* ISO_A3 (not the sub-region's own
+ * id), so a feature's owner is found via its `properties.parent` (the ISO_A3 the
+ * client stamps from the GeoJSON `parent` property — see WorldMap) and then
+ * `regionOwner`. This is the single shared source of truth for that resolution,
+ * so the "use `parent`, never the sub-region `id`/repacked `feature.id`" rule
+ * lives in one tested place rather than in the React component.
+ *
+ * Returns `undefined` for a missing feature/parent or an unowned country.
+ */
+export function mapFeatureOwner(
+  regions: RegionMap,
+  feature: { properties?: { parent?: unknown } } | null | undefined,
+): RegionOwner | undefined {
+  const parent = feature?.properties?.parent;
+  return regionOwner(regions, typeof parent === 'string' ? parent : '');
 }
 
 /** Server -> client Server-Sent Events payload (see server/index.ts /sse). */