doxa-life/doxa-maps
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

README: screenshots first — one per capability, three deployments shown live, the studio last
Some checks are pending
build-gate / build (push) Waiting to run
Details

Browse source 
- The five capabilities each lead with a current screenshot; the Research
  Gallery's composition tree folds into a <details> block.
- Deployment: (1) the prayer map in a host page's iframe, (2) the Simple
  Research dashboard as the phone app, (3) the whole Research Gallery
  JS-embedded on dx-life's research page. WordPress/Disciple Tools and Tauri
  are stated as proven proofs of concept, not production-ready.
- The Plugin Studio closes the README with its current screenshot, the
  four-command start and the command table.
- 4,151 -> 1,330 words. Every image retaken against the current build.
- readme-shots: deploy2 shoots research-map-plus-grid at phone size; deploy3
  shoots a running dx-life (DXLIFE_URL=...), skipped when it is not set;
  an http(s) path is used as-is. Retired four images nothing shows any more.
This commit is contained in:
doxa-maps-88655c70 2026-09-24 19:55:20 +00:00
parent b026c3ef83
commit d1fc658de4
14 changed files with 151 additions and 440 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

540
README.md
View file

@ -1,165 +1,80 @@
# dx-maps — one build, maps that embed everywhere
> **The map cruncher.** Many hand-built maps go in; one shared library, one repo and one build
> come out — and every map fans out to five deployment targets from the same artifacts.
>
> ```text
> map · map · map · map · map · map · map (7 production maps, once 7 codebases)
> \ \ | | | / /
> +----- plugin-designs/ ------+ one folder per plugin, free zone
> |
> library/ (@map) shared, parameterized, high-bar zone
> |
> ONE bun run build
> |
> doxa-maps/ (drop-anywhere tree: bundles + leaf pages + manifest.json)
> / | \ \ \
> iframe JS-embed mobile WordPress desktop
> (proven) (proven) (built) (built) (built)
> ```
**Write a map once in `plugin-designs/<your-map>/`, run one build, and drop it on any site** —
iframe, script embed, mobile app — or open every map at once as one app. Five plugin
capabilities, five deployment methods, one shared library, one build.
**A Vite bundler that turns each map into a self-contained web component.** Write a map in
`plugin-designs/<your-map>/`, run one build, and get a folder you can drop on any host — iframe it,
script-embed it, wrap it as a mobile app, or open every map at once as one app.
| What dx-maps set out to do | Proof |
|---|---|
| **One build → one folder** you can drop on any host | `bun run check:drop` |
| **Every map embeddable** from a copy-paste snippet | [deployment methods](#the-5-deployment-methods) · `bun run check:embed-targets` |
| **Every map interoperable** through props and events | `bun run verify:interop` |
| **One app nests every map** — and each stays embeddable on its own | [capability 5](#capability-5--app-shell-the-research-gallery) · `bun run check:composite-reg` |
| **5 capabilities × 5 deployment methods** | `bun run verify:5-caps` |
| **Shared library, private plugins** — reuse without breaking each other | `bun run check:library-index` |
| **Many agents, one green `main`** | [agent swarm](#build-it-with-an-agent-swarm) |
---
## What dx-maps is for — and how each objective is met
## The 5 plugin capabilities
Maps multiply a prayer movement only when they can live on *every* partner's site, not just one.
dx-maps exists to make that cheap. It set out to meet seven objectives; each one is met by something
you can open or run, not by a claim.
A capability is **how much a plugin nests**, from one element (1) to an app of apps (5). Every
screenshot is a real bundle from this repo's build.
| # | Objective | How it is met | See it / check it |
|---|-----------|---------------|-------------------|
| 1 | **One build → one folder.** Seven maps that were seven codebases become one repo and one build. | `bun run build` writes a single drop-anywhere tree, `public/doxa-maps/`, with a `manifest.json` describing every bundle. | `bun run check:drop` · `bun run check:settled` |
| 2 | **Every map is embeddable.** Any map, on any site, with a copy-paste snippet. | Each bundle is one custom element; `manifest.json` ships an iframe snippet and an SRI-pinned `<script>` snippet for it. | [Deployment methods](#3-the-5-deployment-methods) · `bun run check:embed-targets` |
| 3 | **Every map is interoperable.** Maps talk to each other through props and events. | Composites wire their children with props, events and shared layouts — no copy-pasted code. | `bun run verify:interop` |
| 4 | **One app nests every map — and each stays independently embeddable.** | The **Research Gallery** is a single capability-5 plugin that nests all seven production maps. | [The Research Gallery](#1-the-research-gallery--five-capabilities-in-one-plugin) · `bun run check:composite-reg` |
| 5 | **5 capabilities × 5 deployment methods.** Anything you build, at any tier, ships everywhere. | A plugin's tier is read from its files; every tier builds to the same tree, and the tree feeds all five methods. | [Capabilities](#2-the-5-plugin-capabilities--most-advanced-first) · `bun run verify:5-caps` |
| 6 | **A clean shared/private boundary.** Reuse without breaking each other. | `library/` holds shared, parameterized pieces (generated index); anything map-specific stays in its own `plugin-designs/` folder. | [reference-library-index.md](./documentation/reference-library-index.md) · `bun run check:library-index` |
| 7 | **Many builders, one green `main`.** The repo is built to be worked by a swarm of agents at once. | One agent per plugin, one worktree each, and every change landed through a merge queue. | [Build it with an agent swarm](#5-build-it-with-an-agent-swarm) |
### Capability 5 — app shell: the Research Gallery
Plus one practical objective: **a token-free option.** Mapbox is the default engine; setting a single
prop, `provider: "maplibre"`, swaps in MapLibre so a partner running many embeds needs no Mapbox key.
`bun run check:provider-switch` proves the switch really changes the engine.
## Contents
1. **[The Research Gallery](#1-the-research-gallery--five-capabilities-in-one-plugin)** — the showcase: five capabilities in one plugin.
2. **[The 5 plugin capabilities](#2-the-5-plugin-capabilities--most-advanced-first)** — what you can build, most advanced first.
3. **[The 5 deployment methods](#3-the-5-deployment-methods)** — where a plugin can run.
4. **[The Plugin Studio](#4-the-plugin-studio)** — ★ where you *work*, and every command to get it running. Start here if you are new.
5. **[Build it with an agent swarm](#5-build-it-with-an-agent-swarm)** — how to run many agents on one laptop without collisions.
---
## 1. The Research Gallery — five capabilities in one plugin
The Research Gallery (`plugin-designs/doxa-maps-spa/`) is the product a user opens. It is **one
capability-5 plugin** — one custom element, `<doxa-maps-spa>` — and every tab inside it is a
**real, independently embeddable plugin** from a lower tier. Nothing is copied into it and nothing is
framed: each tab loads its own bundle and mounts that bundle's own custom element.
One plugin, one element (`<doxa-maps-spa>`), and every tab inside it is a real plugin from a lower
tier that you can still embed on its own. `plugin-designs/doxa-maps-spa/`
![Capability 5 — the Research Gallery app shell (doxa-maps-spa)](documentation/readme-images/cap5-doxa-maps-spa.png)
This is how five different capabilities compose into one:
<details>
<summary><b>What the Research Gallery is made of — all five capabilities in one plugin</b></summary>
```text
Research Gallery <doxa-maps-spa> capability 5 — app shell
│
Research Gallery <doxa-maps-spa> capability 5
├─ Dashboards
│ ├─ Big Picture dashboard-plus-grid capability 4 — composite
│ │ ├─ research dashboard research-dashboard capability 3 — monolithic
│ │ └─ people-groups grid people-groups-grid capability 2 — prop-table
│ ├─ Simple Research research-map-plus-grid capability 4 — composite
│ │ ├─ research map doxa-research-map capability 3 — monolithic
│ │ └─ people-groups grid people-groups-grid capability 2 — prop-table
│ └─ Regions regions-mfe capability 4 — composite
│ ├─ regions list regions-list capability 1 — single
│ └─ region dashboards region-dashboards capability 1 — single
│ ├─ Big Picture dashboard-plus-grid capability 4
│ │ ├─ research dashboard research-dashboard capability 3
│ │ └─ people-groups grid people-groups-grid capability 2
│ ├─ Simple Research research-map-plus-grid capability 4
│ │ ├─ research map doxa-research-map capability 3
│ │ └─ people-groups grid people-groups-grid capability 2
│ └─ Regions regions-mfe capability 4
│ ├─ regions list regions-list capability 1
│ └─ region dashboards region-dashboards capability 1
├─ Prayer Mobilization
│ ├─ UPG-100 List upg-100-mfe capability 4 — composite
│ │ ├─ list upg-100-list capability 1 — single
│ │ └─ poster wall poster-wall capability 1 — single
│ └─ Prayer Progress doxa-simple-map (prayer) capability 2 — prop-table preset
│ ├─ UPG-100 List upg-100-mfe capability 4
│ │ ├─ list upg-100-list capability 1
│ │ └─ poster wall poster-wall capability 1
│ └─ Prayer Progress doxa-simple-map capability 2
├─ Gospel Research
│ ├─ Cities with Internet connectivity-map capability 1 — single
│ └─ Gospel Resources resources-map capability 1 — single
└─ Experimental (folder) every other bundle, discovered automatically from manifest.json
│ ├─ Cities with Internet connectivity-map capability 1
│ └─ Gospel Resources resources-map capability 1
└─ Experimental every other bundle, discovered automatically
```
What that buys you:
</details>
- **Seven production maps, one URL.** The three sections above are the seven curated tabs.
- **Every tab is still a standalone embed.** Want only the UPG-100 list on a partner site? Embed
`upg-100-mfe` — or just its `upg-100-list` leaf. Taking the whole app apart costs nothing.
- **Proving the whole proves the parts.** When the Research Gallery was embedded cross-origin on a
foreign host page (see [deployment](#3-the-5-deployment-methods)), every nested plugin rode along.
- **New plugins appear on their own.** Any bundle not placed in a named section lands in
*Experimental*, read from the built `manifest.json`. A new folder in `plugin-designs/` shows up with
zero edits to the shell.
### Capability 4 — composite: plugins wired together
The tab order and grouping live in one place, `NAV_GROUPS` in
[`doxa-maps-spa.vue`](./plugin-designs/doxa-maps-spa/doxa-maps-spa.vue); `bun run check:spa-tab-order`
guards it.
Nests lower-tier plugins and wires them with props and events. `plugin-designs/my-upg-100-list/`
---
![Capability 4 — the UPG-100 composite (my-upg-100-list)](documentation/readme-images/cap4-upg100-mfe.png)
## 2. The 5 plugin capabilities — most advanced first
| List (cap 1, embeddable alone) | Poster wall (cap 1, embeddable alone) |
|---|---|
| ![UPG-100 list leaf](documentation/readme-images/cap4-upg100-list.png) | ![UPG-100 poster-wall leaf](documentation/readme-images/cap4-upg100-poster-wall.png) |
A "capability" is **how much a plugin nests** — not how hard it is to use. The tour below starts from
the most advanced thing this repo produces (an app of apps) and walks down to the simplest (one
element), because the top of the ladder is the point: every rung below it stays independently
embeddable. Every screenshot is a real bundle from this repo's build output.
### Capability 3 — multi-view: many views, one element
| # | Capability | What it is | Example bundle |
|---|------------|------------|----------------|
| 5 | **Nested-SPA / app shell** | Many SPAs nested into one deep-linkable app. | `doxa-maps-spa` |
| 4 | **Nested-element SPA** | A composite that nests *other plugins* and wires them with props/events. | `big-picture` |
| 3 | **Monolithic element** | One `root.vue` nests many views internally → one element. | `doxa-research-map` |
| 2 | **Prop-table element** | One `root.vue` + a preset table → many maps from one plugin. | `doxa-simple-map` |
| 1 | **Single element** | One folder → one bundle → one custom element. | `all-people-groups` |
> The tier is decided by the files, not by how simple a folder looks: an `*.instances.json` makes a
> bundle **cap-2** however light it is, and a `meta.json` `type` declares tiers 3/4/5. The authoritative,
> generated answer lives in
> **[documentation/reference-capability-exemplars.md](./documentation/reference-capability-exemplars.md)**
> — cite that file rather than remembering.
### Capability 5 — nested-SPA / app shell
Every plugin in one deep-linkable page. Two cap-5 apps ship, and the difference matters when you embed
one: **`doxa-maps-spa` (the Research Gallery, [section 1](#1-the-research-gallery--five-capabilities-in-one-plugin))
is what an end user gets; `plugin-studio` is what a developer works in.**
*`plugin-studio` — the developer studio*, grouping every built plugin by capability (5 → 1). It is
auto-generated: the build discovers every folder in `plugin-designs/`, so a new plugin appears in the
studio without any wiring. This is [section 4](#4-the-plugin-studio).
![Capability 5 — the developer studio (plugin-studio)](documentation/readme-images/cap5-plugin-studio.png)
### Capability 4 — nested-element SPA
A composite that nests **lower-tier plugins** and wires them with props and events. Each inner plugin
stays independently embeddable, and the composite is embeddable too. `plugin-designs/my-upg-100-list/`
ships three leaves:
| Composite (`upg-100-mfe`) | List (`upg-100-list`) | Poster wall (`poster-wall`) |
|---------------------------|-----------------------|-----------------------------|
| ![Capability 4 — the UPG-100 composite (my-upg-100-list)](documentation/readme-images/cap4-upg100-mfe.png) | ![UPG-100 list leaf](documentation/readme-images/cap4-upg100-list.png) | ![UPG-100 poster-wall leaf](documentation/readme-images/cap4-upg100-poster-wall.png) |
### Capability 3 — monolithic element
A whole multi-view map from one `root.vue`. The trade-off: you cannot embed just one of its tabs.
`plugin-designs/doxa-research-map/`
![Capability 3 — the monolithic research map (doxa-research-map)](documentation/readme-images/cap3-monolithic-research.png)
### Capability 2 — prop-table element
### Capability 2 — presets: one plugin, many maps
One `root.vue`, many maps. `plugin-designs/doxa-simple-map/` ships a preset prop-table
(`simple-map.instances.json`) that renders it three ways — each a standalone embeddable page from the
**same** code.
One `root.vue` plus a preset table. `plugin-designs/doxa-simple-map/`
| Prayer | Engagement | Adoption |
|--------|------------|----------|
@ -167,319 +82,130 @@ One `root.vue`, many maps. `plugin-designs/doxa-simple-map/` ships a preset prop
### Capability 1 — single element
One folder, one `.vue`, one embeddable element. `plugin-designs/all-people-groups/` shows every people
group on one map.
One folder, one `.vue`, one element. `plugin-designs/all-people-groups/`
![Capability 1 — a single-element plugin (all-people-groups)](documentation/readme-images/cap1-single-element.png)
---
## 3. The 5 deployment methods
Ordered easiest to hardest. **Status is stated honestly** — "proven" means it has been run and seen, and
nothing below is upgraded past what the files support.
| # | Method | Status | Command / install |
|---|--------|--------|-------------------|
| 1 | **iframe** on any site | ✅ **proven** | `bun run build`, then paste the `embed.iframe` snippet from `manifest.json` |
| 2 | **Mobile app** (Capacitor, Android) | 🛠️ built, not shot | `bun run check:mobile` (no toolchain) · `bun run phone` needs Android SDK + JDK 17 + `adb` |
| 3 | **JavaScript embed** (`<script src>` + SRI) | ✅ **proven** | `bun run build`, then paste the `embed.script` + `integrity` snippet |
| 4 | **WordPress plugin** (shortcode + block) | 🛠️ built, contract-proven, not shot | `bun run check:wp-embed`, then install `deployment/wordpress/doxa-maps-embed/` |
| 5 | **Desktop app** (Tauri) | 🛠️ built, not shot | `bun run check:tauri` (no toolchain) · `cargo tauri build` needs Rust + webview libs |
**What "not shot" means:** the code exists and its contract test passes, but nobody has captured it
running on a real device or install. Each is blocked by a missing local toolchain, not by missing code —
Android SDK for method 2, a live WordPress for method 4, and a GUI for method 5.
Methods **1 and 3 are the two proven-live paths.** If you need a map on a site today, use one of those.
Both were **certified cross-origin on 2026-09-24** — the entire Research Gallery, embedded on a
foreign host page, every inner plugin riding along (prove the whole = prove the parts):
| Method 1 — iframe on a host site | Method 3 — JS embed on a host site |
|----------------------------------|-------------------------------------|
| ![The cap-5 app inside a host page iframe](documentation/readme-images/deploy1-iframe-hostsite.png) | ![The cap-5 app JS-embedded on a host page](documentation/readme-images/deploy3-js-embed-hostsite.png) |
> For a JS embed on another site the host page sets `window.MAP_TOKEN` (nested elements read it)
> and the serving layer must send `Access-Control-Allow-Origin: *` — the tree is fetched
> cross-origin by `manifest.json`-composed surfaces.
The full per-method command matrix, with every prerequisite, is in
**[documentation/README-SECTION-3-cli-commands.md](./documentation/README-SECTION-3-cli-commands.md)**.
### The Mapbox token (read this before you file a bug)
The maps use Mapbox by default, which needs a `pk.` token. **The token works differently in dev than in
the built tree**, and diagnosing one from the other is the most common way to lose an hour.
| Where | How it gets a token |
|---|---|
| **Dev server** (`bun run dev`) | Baked into the page for you — from `.env` (`VITE_MAPBOX_TOKEN`) if present, otherwise from `token` in `vite.doxa-maps-build-config.json`. |
| **Built pages** (`bun run serve`, or hosted) | **Not baked.** Each page resolves a token at runtime: `?tk=<TOKEN>` on the URL, a token you paste into the page's own input box (kept in `localStorage`), or a token endpoint (`tokenUrl`). |
So on a built leaf page you typically need:
```
http://localhost:4173/doxa-maps/demo-map/demo-map/index.html?tk=pk.your_token_here
```
To use your own token in dev, create a `.env` — it is **gitignored**, so it never reaches the repo:
```bash
printf 'VITE_MAPBOX_TOKEN=%s\n' 'pk.your_token_here' > .env
```
**If a basemap is an empty grey void while the pins still draw, that is the token failing** — not a
broken app.
**Or skip the token entirely.** A public `pk.` token can be restricted to specific URLs in the Mapbox
dashboard, but a JAMstack embed still has nowhere to hide one. So the engine is one prop: set
`provider: "maplibre"` on an instance (or add `?provider=maplibre` to a leaf page) and the map renders
on MapLibre with no Mapbox key. `plugin-designs/doxa-research-map/research-map.instances.json` ships a
ready-made MapLibre instance. The trade-off is deliberate: under MapLibre the place-search bar is
hidden, because the geocoder would still bill the Mapbox key the instance exists to avoid.
> Which bundle sits at which tier is generated, not remembered:
> [documentation/reference-capability-exemplars.md](./documentation/reference-capability-exemplars.md).
---
## 4. The Plugin Studio
## The 5 deployment methods
★ **This is where you work — and the keyword is INTEROPERABILITY.**
### 1. iframe — the prayer map on any site ✅ production
The Plugin Studio is one place to **view all of your plugins at once** and **edit all of them in one
place using your agent**. Every plugin appears in a single view, sorted **highest capability down to
lowest**, so you can see the whole catalogue instead of hunting through folders.
One `<iframe>` tag, no build step. Copy the `embed.iframe` snippet from `manifest.json`.
That sorting is the point. Once you can see every plugin side by side, you can tell your agent **which
ones to group together** — any number of them — and compose them into **higher-capability plugins**
using **props, events and layouts**. Group cap-1 and cap-2 elements and you get a cap-4 nested-element
SPA; group those and you get a cap-5 app shell. That is exactly how the Research Gallery was built.
![Method 1 — the prayer map embedded in a host page's iframe](documentation/readme-images/deploy1-iframe.png)
### Get it running
### 2. Mobile app — Simple Research on a phone ✅ built
Four steps from nothing to every map in one place. You need **git**, **[Bun](https://bun.sh)** and
**Node ≥ 18**.
The Simple Research dashboard (research map + people-groups grid), shipped on its own as a
Capacitor app. `bun run check:mobile` · `bun run phone` (needs Android SDK + JDK 17)
```bash
# 1. Clone (the repo root IS the studio — there is no subfolder to cd into)
git clone https://git.nuxtbase.app/doxa-life/doxa-maps.git
cd doxa-maps
<p align="center"><img src="documentation/readme-images/deploy2-mobile-simple-research.png" alt="Method 2 — the Simple Research dashboard at phone size" width="320"></p>
# 2. Install dependencies
bun install --frozen-lockfile
### 3. JavaScript embed — the Research Gallery on dx-life ✅ production
# 3. Optional — your own Mapbox token for dev (see section 3)
printf 'VITE_MAPBOX_TOKEN=%s\n' 'pk.your_token_here' > .env
The whole capability-5 app on the dx-life research page, from one `<script src>` and one element —
replacing the separate research map, list and regions dashboards the page used to carry. Copy the
`embed.script` snippet (SRI-pinned) from `manifest.json`.
# 4. Open the Plugin Studio
bun run dev
```
![Method 3 — the Research Gallery JS-embedded on the dx-life research page](documentation/readme-images/deploy3-js-embed-dxlife.png)
Then open **http://localhost:5173/** — that root URL *is* the Plugin Studio, with every plugin in one
spot. (If port 5173 is busy Vite picks another one and prints it; read the line it logs.)
### 4. WordPress / Disciple Tools plugin — 🧪 proof of concept
> **You do not need to build first.** The build output in `public/` is committed, so a fresh clone has
> plugins to show the moment the dev server starts.
A shortcode + block plugin in `deployment/wordpress/`; its contract test passes
(`bun run check:wp-embed`). Proven, not production-ready.
Two things worth knowing:
### 5. Desktop app (Tauri) — 🧪 proof of concept
- **`/` is the studio; `/__gallery` is the old staging gallery**, kept but demoted to an explicit URL.
- **Edits hot-reload.** The studio mounts the real `plugin-studio` custom element through its own
`index.js` — the same path the built bundle takes — so what you see is the real element, not a preview.
A desktop binary and `.deb` build from `deployment/src-tauri/` (`bun run check:tauri`). Proven,
not production-ready.
### Every command you need
| Command | What it does |
|---|---|
| `bun run dev` | The Plugin Studio with hot reload, at http://localhost:5173 |
| `bun x vite --port 5299 --strictPort` | A dev server on your own port (see the swarm rules below) |
| `BUNDLE=<name> bun x vite build` | Build **one** bundle, without cleaning anyone else's output |
| `BUILD_ALLOW=1 bun run build` | The full production tree in `public/doxa-maps/` (~4 minutes, takes a lock) |
| `bun run serve` | Serve the built tree at http://localhost:4173, the way production does |
| `bun run check:settled` | Exit 0 = the built tree is safe to measure or publish right now |
| `bun run gates:pre` / `bun run gates:post` | The static and post-build verification gates |
| `bun run verify:5-caps` · `bun run verify:interop` | Prove the five capabilities, and cap-4 interoperability, in a real browser |
| `bun run shots` | Regenerate the README screenshots |
The full list — every deployment command with its prerequisites — is in
[documentation/README-SECTION-3-cli-commands.md](./documentation/README-SECTION-3-cli-commands.md).
### Work with your agent
The studio's companion is your coding agent. The loop:
1. Open the studio (`bun run dev`) and look at the catalogue, sorted cap-5 → cap-1.
2. Tell your agent which plugins to **group** — e.g. *"combine the research map and the people-groups
grid into one composite."*
3. The agent writes a new folder in `plugin-designs/<name>/`, wiring the children with props, events and
a layout from `library/layouts/`.
4. Refresh the studio. The new, higher-capability plugin is there.
**The whole contract is: write your app inside `plugin-designs/<your-map>/`.** There is no registration
step and no per-plugin wiring — the build discovers every folder under `plugin-designs/`. Copy
`plugin-designs/template-bundle/` to start a new one.
Two shared layouts do the composing, both in `library/layouts/`:
- **`VerticalTabsLayout`** — one element visible at a time, lazy-mounted on first open.
- **`StackLayout`** — the opposite: elements stacked top-to-bottom at natural height, so the page
scrolls through them.
### The production build
The dev server is for working; **you do not need a build to see a change.** When you want the
deployable tree:
```bash
BUILD_ALLOW=1 bun run build # ~4 minutes; writes public/doxa-maps/
bun run serve # serve the BUILT tree at http://localhost:4173
```
**`BUILD_ALLOW=1` is required on purpose.** Without it the build refuses (exit 75) and prints cheaper
alternatives, because a full build wipes the output tree that every other agent in a swarm is
reading. On your own machine, with no one else working, set it.
The build also takes a **lock**: if another build is already running it fails fast rather than
corrupting the shared output. Set `BUILD_LOCK_WAIT=600` to queue behind it instead.
**The lock protects a second WRITER. It does not protect a READER.** Every build begins by deleting
`public/doxa-maps/`, so while a build runs the tree is transiently near-empty — and anything reading
it then gets a confident, wrong answer ("that bundle is missing"). Run `bun run check:settled` before
any browser check, any publish, and any claim about what the tree contains, and **grade it by exit
code**: like every gate here, it prints explanatory prose after its verdict, so `| tail -1` will
mislead you. Do not substitute a `pgrep` check — a process list samples an instant, while the lock
knows the queue.
> **Mapbox token:** the dev server bakes one in; built pages take `?tk=pk.…`, a pasted token, or a
> token endpoint. Or skip Mapbox entirely: `provider: "maplibre"` on any instance renders on MapLibre
> with no key. Every command and prerequisite:
> [documentation/README-SECTION-3-cli-commands.md](./documentation/README-SECTION-3-cli-commands.md).
---
## 5. Build it with an agent swarm
## Build it with an agent swarm
This repo is designed for **many builders working in parallel without stepping on each other** — and
the builders can be coding agents on your own laptop. It is **trunk-based development with a merge
queue**, the same model as GitHub's merge queue, GitLab's merge trains and Rust's bors, arranged as
concentric rings:
Trunk-based development with a **merge queue** — the model behind GitHub's merge queue and GitLab's
merge trains. Many agents build in parallel, each in its own worktree; changes land on `main` one
at a time, rebased and gated, so `main` stays green.
![The delegation model: agents in their own worktrees send changes through one merge queue into main](documentation/readme-images/delegation-model.png)
- **`main` — the trunk.** The one shared branch. Everything converges here, and it is always green.
- **Merge queue.** Changes land **one at a time, in order.** Each change is rebased onto the latest
`main` — its author resolves any conflicts — and lands only if the gates pass. A change that fails
leaves the queue; the next one goes. Nothing writes to `main` except the queue.
- **Plugin Studio.** One repo and one shared `library/`, with every plugin visible in one place, so
each builder can see what already exists and reuse it instead of rebuilding it.
- **Agents.** **One agent per plugin, each in its own git worktree.** Each owns its plugin end to end;
its private components stay inside its own `plugin-designs/` folder.
- **Maintainer.** One reviewer — human or agent — keeps everyone honoring the model: plugins built in
the studio, shared components genuinely shared, and every change going through the queue.
The effect is cooperative: every agent races to land working features, but the only way to land is
through the queue, one change at a time, **leaving `main` green.**
The diagram's source is [`documentation/readme-images/src/delegation-model.svg`](./documentation/readme-images/src/delegation-model.svg).
### Spin one up on your laptop
**1. One worktree per agent**, as sibling folders, so no two agents share a working directory:
```bash
git worktree add -b regions/work ../dx-maps-regions main
git worktree add -b upg100/work ../dx-maps-upg100 main
git worktree add -b maintainer/work ../dx-maps-maintainer main
git worktree list
```
# one worktree + one agent per plugin
git worktree add -b regions/work ../dx-maps-regions main
git worktree add -b upg100/work ../dx-maps-upg100 main
**2. One agent per worktree, each owning one plugin.** Start your coding agent in each folder and give
it a single `plugin-designs/<name>/` folder to own. The maintainer gets no plugin; it reviews what
lands and pushes back when shared code is duplicated or a plugin reaches into another's folder.
# one dev server per agent, each on its own port
bun x vite --port 5301 --strictPort
**3. One dev server per agent, each on its own port, always with `--strictPort`:**
```bash
bun install --frozen-lockfile # once per worktree
bun x vite --port 5301 --strictPort # regions agent
bun x vite --port 5302 --strictPort # upg100 agent
```
Without `--strictPort`, Vite silently moves a busy port to the next one — and several gates have
`5173` written into them, so a drifted server leaves those gates reporting a confident wrong answer
about somebody else's page. With `--strictPort` the duplicate exits non-zero instead.
**4. One owner for the full build.** Agents edit source and check their own bundle with
`BUNDLE=<name> bun x vite build`. Only one agent runs `BUILD_ALLOW=1 bun run build`, because every full build wipes
the shared output tree first.
**5. Land through the merge queue.** On one machine, a file lock is a complete merge queue — agents
wait their turn on it (`flock` ships with Linux; on macOS, `brew install flock`):
```bash
# land through the queue: one at a time, rebased, gated
flock /tmp/dx-maps-main.lock sh -c '
git fetch origin &&
git rebase origin/main &&
bun run gates:pre &&
git push origin HEAD:main
'
git fetch origin && git rebase origin/main &&
bun run gates:pre && git push origin HEAD:main'
```
The lock guarantees one landing at a time; the rebase makes the lander resolve every conflict; the
gates keep `main` green. When several machines share one remote, use the hosting platform's merge
queue instead (GitHub merge queue, GitLab merge trains), or protect `main` so only one builder at a
time may push.
One agent owns the full build (it wipes the shared output first); everyone else checks their own
bundle with `BUNDLE=<name> bun x vite build`. A **maintainer** reviews what lands and keeps shared
code shared. Agents joining this repo: read [AGENT-BRIEF.md](./AGENT-BRIEF.md).
Diagram source: [`delegation-model.svg`](./documentation/readme-images/src/delegation-model.svg).
Agents joining this repo should also read [AGENT-BRIEF.md](./AGENT-BRIEF.md).
---
## The Plugin Studio — ★ where you work
Every plugin in one place, sorted by capability. Pick any plugin to run it live, see what it is
composed of, and copy its embed code. Tell your agent which plugins to **group**, and it composes
them into a higher-capability plugin with props, events and a layout — that is how the Research
Gallery was built. *(The studio is being redesigned; this screenshot tracks it.)*
![Capability 5 — the developer studio (plugin-studio)](documentation/readme-images/cap5-plugin-studio.png)
### Get it running
You need **git**, **[Bun](https://bun.sh)** and **Node ≥ 18**.
```bash
git clone https://git.nuxtbase.app/doxa-life/doxa-maps.git
cd doxa-maps
bun install --frozen-lockfile
bun run dev # → http://localhost:5173/ is the Plugin Studio
```
No build needed first — the built tree is committed. To start a plugin, copy
`plugin-designs/template-bundle/` to `plugin-designs/<your-map>/`; the studio finds it automatically.
| Command | What it does |
|---|---|
| `bun run dev` | The Plugin Studio, hot-reloading, at http://localhost:5173 |
| `BUNDLE=<name> bun x vite build` | Build one bundle only |
| `BUILD_ALLOW=1 bun run build` | The full deployable tree in `public/doxa-maps/` (~4 min; refuses without the flag, to protect a shared tree) |
| `bun run serve` | Serve the built tree at http://localhost:4173 |
| `bun run check:settled` | Exit 0 = the built tree is safe to measure right now |
| `bun run gates:pre` · `bun run gates:post` | The verification gates |
| `bun run shots` | Regenerate these screenshots (`ONLY=<name>` for one) |
---
## Repository layout
```text
doxa-maps/
├── plugin-designs/ YOUR maps live here — one folder per plugin (the FREE zone).
│ ├── doxa-maps-spa/ the Research Gallery, capability 5 (nests the production maps)
│ ├── plugin-studio/ the developer studio, capability 5 (nests every plugin)
│ ├── dashboard-plus-grid/ capability-4 composite: research dashboard + people-groups grid
│ ├── my-upg-100-list/ capability-4: UPG-100 list + poster wall
│ ├── doxa-simple-map/ capability-2: one root.vue, three preset maps
│ └── template-bundle/ copy this to start a new plugin
├── library/ the SHARED zone (@map) — reusable, parameterized only.
│ ├── layouts/ VerticalTabsLayout, StackLayout — how composites compose
│ ├── components/ map controls, legends, search, poster, detail panels
│ ├── composables/ map instance, shadow styles, print-in-place, retry
│ └── styles/ colors/ data/ style registry, palettes, lookup tables
├── data/ the public datasets the maps ship with
├── deployment/ Capacitor (mobile), WordPress plugin, Tauri (desktop)
├── documentation/ tutorial · how-to · reference · explanation + architecture
├── internal/ the build generator + the verification gates
└── public/doxa-maps/ the BUILD OUTPUT — the drop-anywhere tree (bundles, leaf pages,
manifest.json). What gets served and embedded.
plugin-designs/ YOUR maps — one folder per plugin, a free zone
library/ the SHARED toolkit (layouts, components, composables) — a high bar
public/doxa-maps/ the build output: the drop-anywhere tree + manifest.json
deployment/ Capacitor · WordPress · Tauri
internal/ the build generator and the gates
documentation/ tutorial · how-to · reference · architecture — start at documentation/README.md
```
**`plugin-designs/` is a free zone.** Your plugin is its own application in its own folder, building to
its own output. Nothing you do there can break another author's map.
**`library/` is a HIGH BAR.** It is multi-tenant — reused by many maps and authors — so every edit is a
breaking-change risk to everyone. Only contribute here when a component is genuinely reusable *and*
parameterized, so other maps can use it. Keep map-specific, non-parameterized code in your own
plugin-design. See [documentation/contributing/](./documentation/contributing/).
---
## More docs
Start at **[documentation/README.md](./documentation/README.md)** — the index of everything below.
| Read this | When |
|---|---|
| **[documentation/develop-a-plugin-and-see-it-live.md](./documentation/develop-a-plugin-and-see-it-live.md)** | ★ the golden path — zero to a plugin live, in 6 steps |
| **[documentation/README-SECTION-3-cli-commands.md](./documentation/README-SECTION-3-cli-commands.md)** | the full per-method CLI + install matrix |
| **[documentation/reference-capability-exemplars.md](./documentation/reference-capability-exemplars.md)** | which bundle is the capability-N example (generated) |
| **[documentation/reference-library-index.md](./documentation/reference-library-index.md)** | the menu of reusable `library/` pieces you can import |
| **[documentation/why.md](./documentation/why.md)** | 2 min — the problem, the idea, one diagram |
| **[documentation/tutorial.md](./documentation/tutorial.md)** | build your first map, step by step |
| **[documentation/how-to.md](./documentation/how-to.md)** | task recipes (embed, data, mobile) |
| **[documentation/architecture/](./documentation/architecture/)** | the deep end — embeddability, app-wrappers, file map |
---
> **Bottom line: maps should be open source, run everywhere, and multiply.** This bundler makes each map
> a self-contained file that embeds on your site, your partners' sites, WordPress, and mobile — from one
> build. The Plugin Studio is where you compose them into something bigger; the Research Gallery is
> what that looks like when you do.
> **Maps should be open source, run everywhere, and multiply.** One build makes each map a
> self-contained file for your site, your partners' sites and a phone. The Plugin Studio is where
> you compose them into something bigger.

BIN
documentation/readme-images/cap4-upg100-list.png
View file

Binary file not shown.
Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 1.1 MiB

After

Width:  |  Height:  |  Size: 1.1 MiB

BIN
documentation/readme-images/cap4-upg100-mfe.png
View file

Binary file not shown.
Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 1.7 MiB

After

Width:  |  Height:  |  Size: 1.5 MiB

BIN
documentation/readme-images/cap4-upg100-poster-wall.png
View file

Binary file not shown.
Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 1.7 MiB

After

Width:  |  Height:  |  Size: 1.6 MiB

BIN
documentation/readme-images/cap5-doxa-maps-spa.png
View file

Binary file not shown.
Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 1.8 MiB

After

Width:  |  Height:  |  Size: 1.9 MiB

BIN
documentation/readme-images/cap5-plugin-studio.png
View file

Binary file not shown.
Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 1,015 KiB

After

Width:  |  Height:  |  Size: 1 MiB

BIN
documentation/readme-images/deploy1-iframe-hostsite.png
View file

Binary file not shown.
Side by side

Before

Width:  |  Height:  |  Size: 565 KiB

BIN
documentation/readme-images/deploy1-iframe.png
View file

Binary file not shown.
Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 1 MiB

After

Width:  |  Height:  |  Size: 1.1 MiB

BIN
documentation/readme-images/deploy2-mobile-simple-research.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 1.2 MiB

BIN
documentation/readme-images/deploy2-mobile-spa.png
View file

Binary file not shown.
Side by side

Before

Width:  |  Height:  |  Size: 1.2 MiB

BIN
documentation/readme-images/deploy3-js-embed-dxlife.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 1.1 MiB

BIN
documentation/readme-images/deploy3-js-embed-hostsite.png
View file

Binary file not shown.
Side by side

Before

Width:  |  Height:  |  Size: 603 KiB

BIN
documentation/readme-images/deploy3-research-dashboard.png
View file

Binary file not shown.
Side by side

Before

Width:  |  Height:  |  Size: 1.1 MiB

51
internal/readme-shots.mjs
View file

@ -153,7 +153,7 @@ async function shot(name, path, {
// frame and loads no tiles of its own).
if (mapboxReferer) await ctx.setExtraHTTPHeaders({ Referer: 'https://doxa.life/' })
const page = await ctx.newPage()
const url = BASE + path + (tokenFree ? '' : (path.includes('?') ? '&' : '?') + 'tk=' + encodeURIComponent(TK))
const url = (/^https?:/.test(path) ? path : BASE + path) + (tokenFree ? '' : (path.includes('?') ? '&' : '?') + 'tk=' + encodeURIComponent(TK))
try {
await page.goto(url, { waitUntil: 'load', timeout: 45000 })
if (waitFor) await page.waitForSelector(waitFor, { timeout: 20000 })
@ -330,39 +330,24 @@ virtualPages.set('/__readme-iframe-host.html', `<!doctype html>
await shot('deploy1-iframe', '/__readme-iframe-host.html',
{ vp: { width: 1000, height: 700 }, wait: 11000, countFrames: true, mapboxReferer: false })
// ---- DEPLOY2: mobile — the SPA at phone viewport ----
// Same correction as cap5: shoot the cap-5 ELEMENT at phone viewport, not the gallery page.
// mapboxReferer:false for the same reason as the other two cap-5 shots — this IS the cap-5 shell,
// just at a phone viewport, and it nests every tab in an iframe.
await shot('deploy2-mobile-spa', '/doxa-maps/doxa-maps-spa/doxa-maps-spa/index.html',
{ vp: { width: 390, height: 844 }, wait: 10000, dsf: 3, mapboxReferer: false })
// ---- DEPLOY2: mobile — the Simple Research dashboard as the phone app ----
// The mobile app ships ONE dashboard, not the whole gallery rail: research-map-plus-grid (the cap-4
// "Simple Research" composite — research map stacked over the people-groups grid), shot at a phone
// viewport. It mounts no iframe, so it keeps the Referer the map tiles need.
await shot('deploy2-mobile-simple-research', '/doxa-maps/research-map-plus-grid/research-map-plus-grid/index.html',
{ vp: { width: 390, height: 844 }, wait: 12000, dsf: 3 })
// ---- DEPLOY3: research dashboard ----
// ★ THE EARLIER NOTE HERE WAS WRONG, AND THE WAY IT WAS WRONG IS WORTH KEEPING (corrected
// 2026-09-21). It read: "research-dashboard OWNS NO MAP — it is an SVG-charts surface (measured:
// 1083 elements, 10 <svg>, ZERO <canvas>)". The MEASUREMENT was real; the INFERENCE inverted it.
// research-dashboard absolutely owns a Mapbox map — src/components/dashboards/DashboardMapPanel.vue
// imports useMapInstance, injects mapboxToken, and adds a vector source. Re-measured live, the page
// DOES build a `mapboxgl-canvas` at 878x445.
//
// ★ "ZERO CANVAS" MEANT THE MAP FAILED TO INITIALISE, NOT THAT NO MAP EXISTS. Reading absence as a
// property of the surface turned a symptom into an architectural "fact", and that fact then
// justified relaxing the readiness check — so the shot stopped waiting for the very thing whose
// absence was the bug, and the README's deploy-3 proof image has shown a BLANK GREY map pane since.
// A weakened assertion that makes a failing check pass is how a defect gets promoted to a design note.
//
// WHY THE PANE IS STILL GREY (a real defect, tracked separately — not this file's to fix):
// the panel sources `mapbox://mapbox.country-boundaries-v1`, and the shared pk. token is URL-
// restricted to doxa.life. Measured: Referer doxa.life -> 200 (3/3), 127.0.0.1 -> 403, none -> 403.
// The STYLE endpoint returns 200 from every origin, which is why other maps paint normally and only
// the tileset-backed choropleth blanks. So the shot machine cannot paint this pane at all today.
//
// `waitFor: CANVAS` is therefore still wrong HERE — not because there is no map, but because the
// canvas genuinely cannot be produced from this origin, and a gate that can never pass gets
// weakened again by the next reader. minElements proves the surface rendered; check:shot-fidelity
// is where "this machine cannot render what the shot must show" belongs.
await shot('deploy3-research-dashboard', '/doxa-maps/research-dashboard/research-dashboard/index.html',
{ waitFor: 'svg', wait: 10000, minElements: 200 })
// ---- DEPLOY3: JS embed — the Research Gallery on a real host site ----
// The whole cap-5 gallery JS-embedded on dx-life's research page (a <script src> plus one element,
// the snippet manifest.json ships). The host is a SEPARATE app, so this shot runs only when its dev
// server is up: DXLIFE_URL=http://127.0.0.1:<port> bun run shots. Without it the shot is skipped
// and the committed image stays as it is.
if (process.env.DXLIFE_URL) {
await shot('deploy3-js-embed-dxlife', process.env.DXLIFE_URL.replace(/\/$/, '') + '/research',
{ vp: { width: 1440, height: 1100 }, wait: 16000, tokenFree: true, minElements: 300 })
} else if (!ONLY || ONLY.includes('deploy3-js-embed-dxlife')) {
console.log(' SKIP deploy3-js-embed-dxlife (set DXLIFE_URL to a running dx-life dev server)')
}
await browser.close()
server.close()