build-gate / build (push) Waiting to run

Details

README: lead with the objectives, showcase the Research Gallery, teach the agent swarm

- Opens with what dx-maps is for: seven objectives, each paired with the gate
  or section that proves it is met.
- New Research Gallery section: the cap-5 app shell and the tree of cap-4..1
  plugins it nests, each still independently embeddable.
- Plugin Studio: clone main (the old branch was 198 commits behind), a command
  table, and a fresh studio screenshot (the old one showed a retired nav and
  tofu icons).
- Agent swarm: renamed to industry terms (trunk-based development, merge queue,
  maintainer), a laptop recipe (worktrees, strict ports, one builder, flock as
  the queue), and a redrawn diagram whose inner ring is an actual queue with
  one gate. SVG source committed next to the PNG.
- MapLibre is now described as it is: a one-prop, token-free engine.
- Removed internal credential/push instructions (AGENT-BRIEF.md covers agents).
- documentation/: fixed 19 dead links left by the docs/ move, removed internal
  references, and listed the working docs in the index.
- readme-shots: ONLY=<name> retakes a single image.

2026-09-24 18:34:02 +00:00

2.9 KiB

Raw Blame History

Contributing to doxa-maps

Everything a contributor needs, short. Recipes live in documentation/how-to.md, lookups in documentation/reference.md, depth in 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.

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?".

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.

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.

2.9 KiB Raw Blame History