swift-river542 9cefd6faa4 Plugin gallery: one generator for the dev server and the build

- internal/playground → internal/plugin-gallery; playground-smoke → plugin-gallery-smoke;
  generate-spa → generate-gallery (scripts: gallery, smoke:gallery; smoke:playground stays as alias)
- generate-gallery exports renderGallery(model, { mode }) — the dev plugin serves the same page
  at / from the discovered registry (dev mode imports the dev entries, ladder popovers on);
  the build writes public/index.html from the manifest (byte-identical to before)
- Docs and probes use the gallery vocabulary

2026-09-16 20:04:18 -05:00

2.9 KiB

Raw Blame History

Contributing to doxa-maps

Everything a contributor needs, short. Recipes live in docs/how-to.md, lookups in docs/reference.md, depth in docs/architecture/.

The mental model — three zones

  library/  (@map)          app-profiles/<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: docs/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: docs/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: contributing/COLORS.md.

One-line recap

Copy app-profiles/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