doxa-maps-cdn/DX-MAPS-GALLERY.md

Research Gallery on /research, and every map served from /dx-maps/

This branch replaces the Research page with the Research Gallery: the research maps, dashboards and lists in one app, filling the page below the site header, on desktop and phone. Every other map on the site now loads from the same build tree.

What changed

public/dx-maps/	Removed on this branch (see Deployment method below): every map loads from the maps CDN. The drop-in branch keeps this folder and serves the tree same-origin.
app/pages/research/index.vue	The Research Gallery. The page loads one script (/dx-maps/doxa-maps-spa/doxa-maps-spa.js) and adds one element (<doxa-maps-spa>), sized to the viewport below the header; its tree-base is built at runtime from the page's own origin. The previous content (the "By Region" link, the single research map and the UUPG list) is kept but switched off: set SHOW_LEGACY_RESEARCH = true in the page to bring it back.
app/composables/useDoxaMap.ts	The home (engagement), pray (prayer) and adopt (adoption) maps now load /dx-maps/doxa-simple-map/doxa-simple-map.js; the research-map key loads /dx-maps/doxa-research-map/doxa-research-map.js. Mapbox GL moves from v3.3.0 to v3.24.0, the version the dx-maps bundles are built and tested with.
app/components/DoxaMapSlot.vue	With no Mapbox token configured, it asks the map for the keyless MapLibre engine (see Map engine). With a token, the config passes through unchanged.
public/embed/map/index.html, public/research/doxa-research-map.html	The same: bundles from /dx-maps/, Mapbox GL v3.24.0.
public/js/doxa-simple-map.js, public/js/doxa-research-map.js	Kept, unused. No page loads them any more (every map loads from /dx-maps/), but they stay in place so nothing DX-life relied on is deleted.

Unchanged on purpose: the element names (<doxa-map>, <doxa-research-map>, <doxa-maps-spa>) and nuxt.config.ts (its isCustomElement lists only those names). public/js/pplr-data-maps.iife.js and /research/pplr-data-maps.html are a separate showcase with no dx-maps equivalent, so they are also unchanged.

Language. The gallery follows the site's language and the language switcher (all 11 locales; Arabic lays out right-to-left).

Map engine. If NUXT_PUBLIC_MAPBOX_TOKEN is set, every map uses Mapbox with that token, as before. If it is not set (for example, a fresh laptop with no .env), every map (the Research gallery and the home, pray and adopt maps) uses the keyless MapLibre engine (OpenFreeMap tiles) instead of refusing to start. So the whole site's maps work with no secrets at all.

Footer. The gallery is a full-page app: it fills exactly the space between the header and the bottom of the screen. The site footer is kept, directly below it, where a scroll reaches it. So the app is never squeezed, and the footer's links stay on the page.

Phone. The gallery opens straight on a map (Simple Research). Its list of views sits behind the ☰ button. Big Picture is marked Desktop only there (it needs a wide screen); every other view works on a phone.

Run it

bun install
bun run dev

Then open http://localhost:3000/research/ (Nuxt prints the port if 3000 is taken). No database is needed — without DATABASE_URL the dev server only logs "skipping migrations". But on this branch /research/ needs NUXT_PUBLIC_DX_MAPS_BASE set to where the dx-maps tree is served (see the two settings below); without it the page says the setting is missing, because the tree's address is read at runtime, never baked in. The quickest local value is a served dx-maps tree, e.g. NUXT_PUBLIC_DX_MAPS_BASE=http://localhost:4610/dx-maps.

• Arabic: http://localhost:3000/ar/research/
• Open a specific view: /research/?tab=prayer-map (also research-map-plus-grid, regions-dashboard, upg-100, and so on).
• Share and embed links in the maps point at the dx-maps tree served from NUXT_PUBLIC_DX_MAPS_BASE.
• To run it against a local dx-maps, and to try the ways a site can take the gallery (drop-in and the plugin-studio subdomain) with the exact ports and settings: documentation/LAPTOP-6WAY.md.

Deployment method: the Research Gallery as the public Plugin Studio (this branch, research-gallery-plugin-studio)

The research subdomain runs the dx-maps container in its public mode: the Plugin Studio, open to everyone, with every research map, dashboard and list, and its published /cdn of production maps. This site sends readers there and loads its own maps from there. Each deployment sets two addresses, read by the server at request time and never baked into a build:

Setting	What it is	VPS	Laptop
NUXT_PUBLIC_RESEARCH_GALLERY_URL	the public Plugin Studio	https://research.<host>/	http://research.localhost:4616/
NUXT_PUBLIC_DX_MAPS_BASE	its published tree, where this site's maps load from	https://research.<host>/cdn/dx-maps	http://research.localhost:4616/cdn/dx-maps

Why request time. About 4,000 pages are prerendered, and a prerendered page carries the build's runtime config. An address read there would be baked into the build, which is how the CDN branch failed. So neither setting is in nuxt.config.ts:

• Links: the menu's Research item, every in-page gallery link and the /regions and /countries index pages go to this site's own /research-gallery?tab=…&lang=…. The server redirects that (302) to the deployment's gallery (server/routes/research-gallery.get.ts).
• Maps: every map (the home, pray and adopt maps, /embed-test, /research, and the static pages under public/) first asks this site's server for the tree (GET /api/dx-runtime), then loads its bundle from there.
• Old links: old /js/doxa-maps/… links are redirected per request to the same path in the tree (server/middleware/legacy-map-links.ts).

When a setting is unset there is no fallback host. /research-gallery answers 503 and the maps say which setting to set. Changing an address needs a restart, not a rebuild.

The menu no longer lists this site's Research page or its Regions page. The Regions item is switched off with off: true in app/utils/nav.ts, not deleted. /research is kept, unlinked, and the region and country detail pages stay. No iframe is used.

/embed-test

/embed-test embeds every web plugin in the dx-maps tree, as JavaScript (no iframe). The list is read at runtime from the tree's manifest.json, never typed: section 1 is every profile with stage: production, section 2 every other profile. A profile whose targets leave out web (a desktop-only plugin, such as Rudder) is skipped. Each card loads its bundle's script and adds the element that bundle defines. A card mounts its plugin when it scrolls into view and removes it when it leaves (browsers allow only a few WebGL maps at once). ?only=<bundle>/<profile> (or a bundle name, comma-separated) shows just those.

Updating the maps

Nothing to do on this site: the CDN serves the current tree.