80 lines
4.3 KiB
Markdown
80 lines
4.3 KiB
Markdown
# Architecture — UPG-100 poster generation
|
||
|
||
> The simple overview is in `library/scripts/posters/README.md`. This is the full reference for the
|
||
> generator: files, environment, pipeline, and the gotchas that have bitten before.
|
||
|
||
The poster generator for the **my-upg-100-list** profile renders one 3ft × 3ft print poster per
|
||
zone (28 today) from the profile's own data.
|
||
|
||
**It lives inside doxa-maps on purpose.** It used to sit outside the repo in a sibling generator
|
||
folder and reach in for data via a `UPG100_DATA_PATH` env var. That cost real bugs: forget the var
|
||
and it silently rendered a **stale duplicate** of `clusters.json` — which is how Nepal, and later
|
||
Bangladesh + Bhutan, vanished from posters that looked fine otherwise. The generator and the data
|
||
it reads now ship together.
|
||
|
||
## Run it
|
||
|
||
```bash
|
||
bun run posters # all 28 posters -> out/posters/*.html
|
||
ONLY=asia-india-tamil-nadu bun run posters:one # just one (fast, ~15s)
|
||
bun run posters:shoot # HTML -> PNG @3000x3000 (Playwright/Firefox)
|
||
bun run posters:gallery # review pages -> out/index.html + out/hd.html
|
||
bun run posters:export # region folders -> ../../../upg-100-posters/
|
||
```
|
||
|
||
The full pipeline, in order:
|
||
|
||
```
|
||
posters -> posters:shoot -> (convert to WebP previews) -> bun run build
|
||
```
|
||
|
||
The WebP step feeds `plugin-designs/my-upg-100-list/assets/previews/`, which is what the poster wall
|
||
shows in the app. **A template change is not visible in the app until previews are regenerated and
|
||
the app is rebuilt.**
|
||
|
||
## Files
|
||
|
||
| File | What it does |
|
||
|---|---|
|
||
| `generate.mjs` | THE template. Reads the profile data, writes one HTML poster per zone. |
|
||
| `shoot.mjs` | Screenshots each poster to PNG (Firefox — never Chromium; privacy-first policy). |
|
||
| `poster-regions.mjs` | The region map (India, Africa, …). Shared by both gallery builders. |
|
||
| `build-gallery.mjs` | `out/index.html` — browsable preview grid, sectioned by region. |
|
||
| `build-hd-gallery.mjs` | `out/hd.html` — full-resolution review + copy-to-clipboard. |
|
||
| `export-public.mjs` | Copies PNGs into region folders OUTSIDE the repo (see below). |
|
||
| `snapshots/` | Frozen template versions. v5 is the approved current; v1–v4 are the lineage. |
|
||
|
||
## Environment
|
||
|
||
| Var | Default | Notes |
|
||
|---|---|---|
|
||
| `SPARSE=1` | — | **Required.** Selects the approved template. Without it you get the older full-vision layout. |
|
||
| `FORMAT=3x3` | `3x4` | 1500×1500 square sheet. |
|
||
| `OFFLINE=1` | — | Use the cached `out/_records.json` instead of calling the API. |
|
||
| `VITE_API_BASE_URL` | — | Satisfies the fail-closed config gate. No request is made under `OFFLINE=1`. |
|
||
| `ONLY` | — | Build a single zone by `zoneKey`. |
|
||
| `UPG100_DATA_PATH` | the profile in this repo | Only override to test against other data. |
|
||
| `SERIES_INDEX` / `SERIES_NAME` | derived / `List of 100 UPG's` | Series line on the sheet. |
|
||
|
||
## Two things that will bite you
|
||
|
||
**1. The exported PNGs must NOT go in `public/`.** `capacitor.config.json` sets `webDir: "public"`
|
||
and Capacitor packages that directory wholesale — no per-path exclude. The export is ~52 MB, and
|
||
the per-bundle vite build also fans the served root into every MFE, so it duplicated **11×**
|
||
(631 MB) when it lived there. `export-public.mjs` therefore writes to `../../../upg-100-posters/`, a
|
||
sibling of the repo. Desktop/web can serve from there or a CDN; the phone gets posters from a CDN
|
||
or generates on device.
|
||
|
||
**2. Fail-loud guards, not silent overlaps.** `generate.mjs` throws if the header would be drawn
|
||
over the map frame, or if the below-map block would run off the sheet. Raise the constant or tighten
|
||
the copy — never delete the guard. Both have caught real regressions (`west-africa`, `sudan`,
|
||
`gujarat`, `oceania-indonesia`).
|
||
|
||
## Measurement discipline
|
||
|
||
SVG `<text>` does not word-wrap, so all multi-column setting is measured in the generator via
|
||
`CHADV -> textW -> wrapPx -> paraInto`. **That estimator is calibrated for Lato at body sizes and is
|
||
wrong elsewhere** — measured drift: Georgia bold display type runs ~1.35× wider than predicted, bold
|
||
digits ~0.98em against an assumed 0.63em, mixed bold/regular runs ~10% narrower. Every size that
|
||
must fit a box is therefore taken from the **rendered** artefact (`getBBox`), not from the formula.
|
||
When adding new display text, render it and measure before trusting a computed size.
|