From eb5545da69b85b0f5789a8ad0b52a08e005eb764 Mon Sep 17 00:00:00 2001
From: doxa-maps <noreply@doxa.life>
Date: Wed, 16 Sep 2026 02:02:24 +0000
Subject: [PATCH] Deep-link preload + library/README (architecture clarity)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Deep links (#/research-map etc.) now get a modulepreload for their resolved
  bundle at parse time, parallelizing the fetch with the Mapbox peer — the
  static preload only warmed the default landing bundle. Map mirrored from the
  PROFILES registry with cross-referenced maintenance comments.
- library/README.md: the missing top-level orientation for the shared template
  (@map) — folder-by-folder, paired with app-profiles/README and the
  components WARNING.
---
 layouts/app-wrapper-material/index.html | 33 +++++++++++++++++++++++++
 library/README.md                       | 22 +++++++++++++++++
 public/index.html                       | 33 +++++++++++++++++++++++++
 3 files changed, 88 insertions(+)
 create mode 100644 library/README.md

diff --git a/layouts/app-wrapper-material/index.html b/layouts/app-wrapper-material/index.html
index 5930338dd..daea0ccb3 100644
--- a/layouts/app-wrapper-material/index.html
+++ b/layouts/app-wrapper-material/index.html
@@ -10,6 +10,37 @@
 <link rel="preconnect" href="https://api.mapbox.com" crossorigin />
 <link rel="preconnect" href="https://pray.doxa.life" crossorigin />
 <link rel="modulepreload" href="./doxa-maps/doxa-simple-map/doxa-simple-map.js" />
+<script>
+// DEEP-LINK PRELOAD — the static modulepreload above only warms the DEFAULT
+// landing bundle; a #/research-map deep link used to fetch its bundle strictly
+// AFTER the module ran. This tiny script reads the hash at parse time and adds a
+// modulepreload for the resolved profile's bundle so the fetch parallelizes with
+// the Mapbox peer below. KEEP THIS MAP IN SYNC with the PROFILES registry at the
+// bottom of this file (each entry's `src`) — same ids, same srcs.
+(function(){
+  var M = {
+    'prayer-progress':'./doxa-maps/doxa-simple-map/doxa-simple-map.js',
+    'upg-100-list':'./doxa-maps/my-upg-100-list/my-upg-100-list.js',
+    'countries-map':'./doxa-maps/country-posters/country-posters.js',
+    'key-city-posters':'./doxa-maps/key-cities/key-cities.js',
+    'cities-with-internet':'./doxa-maps/cities-internet/cities-internet.js',
+    'gospel-resources':'./doxa-maps/gospel-resources/gospel-resources.js',
+    'research-map':'./doxa-maps/doxa-research-map/doxa-research-map.js',
+    'research-dashboard':'./external/research-dashboard-map.js',
+    'upg-neighbor':'./external/upg-neighbor.js',
+    'upg-neighbor-lab':'./external/upg-neighbor.js'
+  }
+  try {
+    var id = decodeURIComponent((location.hash || '').replace(/^#\/?/, '')).trim()
+    var src = M[id]
+    if (src && !src.endsWith('doxa-simple-map.js')) {
+      var l = document.createElement('link')
+      l.rel = 'modulepreload'; l.href = src
+      document.head.appendChild(l)
+    }
+  } catch (e) { /* never block boot over a preload */ }
+})()
+</script>
 
 <!-- ── Mapbox GL peer: loaded ONCE by the wrapper (the shell owns the version).
      Profile bundles never import mapbox-gl — they use the `window.mapboxgl`
@@ -755,6 +786,8 @@ const PROFILES = {
   // NOTE its element tag is <doxa-map>, NOT <doxa-simple-map> — the bundle
   // registers both, and the generated instance pages use <doxa-map>. Config is
   // copied from that page's BASE_CONFIG so we match the shipped contract exactly.
+  // NOTE: each entry's `src` is mirrored in the DEEP-LINK PRELOAD map at the top
+  // of this file — update both when adding/moving a bundle.
   'prayer-progress': {
     tag:    'doxa-map',
     src:    './doxa-maps/doxa-simple-map/doxa-simple-map.js',
diff --git a/library/README.md b/library/README.md
new file mode 100644
index 000000000..1b4636119
--- /dev/null
+++ b/library/README.md
@@ -0,0 +1,22 @@
+# library/ (`@map`) — the shared map template
+
+**The other half of the architecture** (see [`../app-profiles/README.md`](../app-profiles/README.md)):
+every map in `app-profiles/<your-map>/` composes the reusable, parameterized pieces that live here.
+Fix something here and **every map benefits** on the next build; break something here and every map
+breaks — read [`components/WARNING.md`](./components/WARNING.md) before touching shared pieces.
+
+| Folder | What lives there |
+|---|---|
+| `ProfileLoader.vue` | The root of every bundle: parses `profile-config`, loads the profile, provides the stores + config |
+| `components/` | Shared UI — map, legends, controls, popup (PeopleGroupDetail), tables, charts, hints ([README](./components/README.md)) |
+| `composables/` | Shared logic — map engine (`useMapInstance`), provider switch, shadow-DOM styles, theming |
+| `stores/` | Per-instance Pinia stores (ui / map / data) — provided by ProfileLoader, injected by children |
+| `api/` | Data-source registry (`sources.json`) + fetch layer — the JAMstack runtime wiring |
+| `colors/` | Color sets maps opt into via `profile-config.colorSet` |
+| `i18n/` | The shared string catalogs (all maps speak the same languages) |
+| `data/` | Small shared datasets baked at build time (big served data lives in `../data/`) |
+| `constants/` | Shared constants |
+| `scripts/` | Maintainer pipelines (posters, research) — not part of any bundle |
+
+**The rule of thumb** (same as WARNING.md): *custom code in your app-profile, reusable code here —
+and things only move from the first to the second once they've earned it.*
diff --git a/public/index.html b/public/index.html
index 647fd689c..85f6e259c 100644
--- a/public/index.html
+++ b/public/index.html
@@ -10,6 +10,37 @@
 <link rel="preconnect" href="https://api.mapbox.com" crossorigin />
 <link rel="preconnect" href="https://pray.doxa.life" crossorigin />
 <link rel="modulepreload" href="./doxa-maps/doxa-simple-map/doxa-simple-map.js" />
+<script>
+// DEEP-LINK PRELOAD — the static modulepreload above only warms the DEFAULT
+// landing bundle; a #/research-map deep link used to fetch its bundle strictly
+// AFTER the module ran. This tiny script reads the hash at parse time and adds a
+// modulepreload for the resolved profile's bundle so the fetch parallelizes with
+// the Mapbox peer below. KEEP THIS MAP IN SYNC with the PROFILES registry at the
+// bottom of this file (each entry's `src`) — same ids, same srcs.
+(function(){
+  var M = {
+    'prayer-progress':'./doxa-maps/doxa-simple-map/doxa-simple-map.js',
+    'upg-100-list':'./doxa-maps/my-upg-100-list/my-upg-100-list.js',
+    'countries-map':'./doxa-maps/country-posters/country-posters.js',
+    'key-city-posters':'./doxa-maps/key-cities/key-cities.js',
+    'cities-with-internet':'./doxa-maps/cities-internet/cities-internet.js',
+    'gospel-resources':'./doxa-maps/gospel-resources/gospel-resources.js',
+    'research-map':'./doxa-maps/doxa-research-map/doxa-research-map.js',
+    'research-dashboard':'./external/research-dashboard-map.js',
+    'upg-neighbor':'./external/upg-neighbor.js',
+    'upg-neighbor-lab':'./external/upg-neighbor.js'
+  }
+  try {
+    var id = decodeURIComponent((location.hash || '').replace(/^#\/?/, '')).trim()
+    var src = M[id]
+    if (src && !src.endsWith('doxa-simple-map.js')) {
+      var l = document.createElement('link')
+      l.rel = 'modulepreload'; l.href = src
+      document.head.appendChild(l)
+    }
+  } catch (e) { /* never block boot over a preload */ }
+})()
+</script>
 
 <!-- ── Mapbox GL peer: loaded ONCE by the wrapper (the shell owns the version).
      Profile bundles never import mapbox-gl — they use the `window.mapboxgl`
@@ -755,6 +786,8 @@ const PROFILES = {
   // NOTE its element tag is <doxa-map>, NOT <doxa-simple-map> — the bundle
   // registers both, and the generated instance pages use <doxa-map>. Config is
   // copied from that page's BASE_CONFIG so we match the shipped contract exactly.
+  // NOTE: each entry's `src` is mirrored in the DEEP-LINK PRELOAD map at the top
+  // of this file — update both when adding/moving a bundle.
   'prayer-progress': {
     tag:    'doxa-map',
     src:    './doxa-maps/doxa-simple-map/doxa-simple-map.js',