9dc4dda8cf
Some checks are pending
build-gate / build (push) Waiting to run
Driver 2026-09-21: 'a folder called deployment which will store the capacitor
folder, wordpress folder and tauri folder', and 'a folder called documentation
to store the contributing folder so docs are in one place'.
docs/ + contributing/ + CONTRIBUTING.md -> documentation/ (three doc homes into
one). capacitor/ + wordpress/ + src-tauri/ -> deployment/.
The public/ -> dist/ rename the Driver asked about is NOT here: after seeing the
measured blast radius (855 tracked files, 54 source refs, and public/ is the
served web-root four consumers point at) the Driver withdrew it - 'keep the
public folder the same'.
Path references were rewritten mechanically (258 across 87 files), but three
classes needed hand fixes because a prefix regex cannot see them:
- join(ROOT,'docs',...) in 10 internal scripts - a quoted SEGMENT, not a prefix
- tauri frontendDist '../public' -> '../../public', since src-tauri is now one
level deeper; check:tauri caught this exactly as the card predicted
- the WordPress contract test's dirname(__DIR__,2) -> 3, same reason
Also reverted one over-reach: the rewrite renamed a FINDING-CATEGORY label
'docs' in public-hygiene-check.mjs, which is a rule name in its own header, not
a path.
Verified: full build ALL GUARDS PASS, SRI consistent; check:tauri, check:mobile
(cap sync + webDir OK), check:wp-embed, quoted-scripts, capability-citations,
capability-exemplars, library-index, public-hygiene, parse and drop all pass.
61 lines
3 KiB
Markdown
61 lines
3 KiB
Markdown
# Contributing to doxa-maps
|
|
|
|
Everything a contributor needs, short. Recipes live in [documentation/how-to.md](./documentation/how-to.md),
|
|
lookups in [documentation/reference.md](./documentation/reference.md), depth in
|
|
[documentation/architecture/](./documentation/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](./documentation/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/doxa-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?"](./documentation/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.
|