2509a6e347
- Deployment is now organised around what the build makes: (1) one web folder (536 files, 76 MiB), embedded by iframe and JavaScript (proven) and WordPress (just for fun); (2) the mobile app (Capacitor, built); (3) the desktop app (Tauri, proof of concept). A hosting table says where the folder can go: dx-life's public/, Cloudflare Pages drag-and-drop (fits its 1,000-file / 25 MiB limits), GitHub + jsDelivr (JS embeds only: measured, jsDelivr serves HTML as text/plain), or any web server, with the one _headers line JS embeds need. No Docker. The diagram and the map-cruncher picture say three outputs. - Languages: 11 locales via ?lang=, Arabic right to left, with an Arabic shot of UPG-100 (Big Picture still leaks English in Arabic; reported). The partner profile-config locale is deliberately not documented until it is fixed. - check-shot-freshness and check-shot-distinctness parsed only '...' paths, so after44ef31b2turned them into `/${TREE_NAME}/...` templates they saw 2 of 26 shots: distinctness failed, freshness passed vacuously and hid 22 stale shots. Both now accept either form and resolve TREE_NAME, and exit 75 (NOT MEASURED) unless every `await shot(` call is parsed (the one dynamic dx-life call is marked). Negative-tested. The 22 shots are retaken and checked by eye. - how-to: the shell no longer overwrites the Studio (it now lives in the output folder); README serve line points at doxa-maps/index.html. - Docs follow the rename to dx-maps (09014f8a): every output-folder path and URL in README, how-to, reference, CONTRIBUTING, the CLI section and the develop guide now says public/dx-maps/. The repo name, the config file name, the WordPress plugin folder and the doxa-* tag names are unchanged (tags are a separate landing). - Hosting: a live example, the dx-life branch research-gallery, which drops the folder into dx-life public/ and fills /research with the Research Gallery.
61 lines
2.9 KiB
Markdown
61 lines
2.9 KiB
Markdown
# Contributing to doxa-maps
|
|
|
|
Everything a contributor needs, short. Recipes live in [documentation/how-to.md](./how-to.md),
|
|
lookups in [documentation/reference.md](./reference.md), depth in
|
|
[documentation/architecture/](./architecture/).
|
|
|
|
## The mental model — three zones
|
|
|
|
```
|
|
library/ (@map) plugin-designs/<map>/ internal/
|
|
shared, parameterized ──► your map: its screens ──► the build machine
|
|
legend · map · controls (.vue) + private colors, (scripts, staging)
|
|
REUSE, never customize api wiring, components NEVER touch
|
|
per-map BUILD EVERYTHING HERE
|
|
```
|
|
|
|
Rule of thumb: **local by default** — code moves into `library/` only when a *second* map
|
|
genuinely needs it. One fix in `library/` reaches every map on the next build.
|
|
|
|
## Two ways one bundle shows many maps
|
|
|
|
- **Pattern A — parameterized**: one `.vue`, many instances differing only by config
|
|
(`*.instances.json` → the build emits one standalone page per instance).
|
|
- **Pattern B — multi-profile**: several `.vue` screens in one bundle, selected by
|
|
`profile-config.profile`.
|
|
|
|
Pick A when the maps differ by *configuration*, B when they differ by *layout/behavior*.
|
|
Full walkthrough + the migration story:
|
|
[documentation/architecture/patterns-and-provenance.md](./architecture/patterns-and-provenance.md).
|
|
|
|
## The two build steps (never confuse them)
|
|
|
|
| Command | What | Writes to `public/`? |
|
|
|---|---|---|
|
|
| `bun run dev` | HMR plugin gallery at `localhost:5173` — iterate on a map in isolation | **No** |
|
|
| `bun run build` | every bundle → `public/dx-maps/<bundle>/<bundle>.js` + generated pages | **Yes** |
|
|
|
|
To see a change on the served site: `bun run build` (or `BUNDLE=<name> bun run build:bundle`),
|
|
then refresh. `dev` never updates the served tree.
|
|
|
|
**Two-terminal workflow** for integration work: terminal 1 `bun run build:watch` (rebuilds
|
|
into `public/` on save) · terminal 2 serves the host site / `public/`.
|
|
|
|
## Where the bundles go
|
|
|
|
`public/` is the committed web-root — serve it from anywhere and every map is embeddable from
|
|
it (script tag or the generated per-map page). Same-origin vs external-CDN modes, `paths`,
|
|
`embedBaseUrl`: [documentation/how-to.md → "Where do the maps get served from?"](./how-to.md).
|
|
|
|
## Ground rules
|
|
|
|
- Never edit `library/` to customize one map (bundle-private code goes in your `src/`).
|
|
- Never bake tokens or data into a bundle — everything arrives at runtime via `profile-config`.
|
|
- Before a PR: `bun run build && bun run verify` must pass (adds drop-portability + parse gates).
|
|
- Colors are values, not logic: [documentation/contributing/COLORS.md](./contributing/COLORS.md).
|
|
|
|
## One-line recap
|
|
|
|
Copy `plugin-designs/template-bundle/`, change exactly four things (folder name, tag in
|
|
`index.js`, tag/profile strings in `index.html`, `.vue` filenames), build everything inside
|
|
your folder from `@map` blocks, `bun run build`, embed the snippet. That's the whole job.
|