doxa-life/doxa-maps

History

doxa-maps-88655c70 64731f2f3e Some checks are pending build-gate / build (push) Waiting to run Details Document why a gate cannot import plugin source, and stop teaching public binds Three docs still told a reader to start a server on every interface: the reference recipe for the share round-trip, the quoted scripts block, and app-wrappers.md. Agents followed those recipes faithfully, which is how twenty publicly bound http.server processes accumulated on this box. All three now bind 127.0.0.1. check:quoted-scripts caught the second one on its own. Also adds the gate-authoring constraint that just broke a build. Plugin and library source is written for Vite, not Node, and fails two ways: the @map alias is unresolvable (hit first), and import.meta.glob is undefined in 18 files including 11 of the 20 plugin index.js. A new check:facet-cascade imported the dashboard config, reached library/colors/_registry.js transitively, and threw -- while already wired into build:unlocked, so the build failed for a reason unrelated to the code being built. The counts in that section were measured, not estimated. A first draft said "every plugin index.js" and the real number is 11 of 20; it also blamed the glob when the first error is actually the alias. States the two rules that follow: build:unlocked is only for gates that run clean in plain Node with no browser and no network, and a gate gets run before it gets wired in -- a broken gate in the build chain is worse than no gate, because it goes red for the wrong reason and trains people to skip the step. Records the other box constraints that have each produced a wrong answer: Node 20 (no fs.glob), bfs find rejecting relative -newermt, no hardware WebGL, and bunx not existing.		2026-09-22 17:40:11 +00:00
..
app-wrappers.md	Document why a gate cannot import plugin source, and stop teaching public binds	2026-09-22 17:40:11 +00:00
color-strategies.md	consolidate docs into documentation/ and deployment shells into deployment/	2026-09-21 23:23:23 +00:00
components.md	consolidate docs into documentation/ and deployment shells into deployment/	2026-09-21 23:23:23 +00:00
data-sources.md	consolidate docs into documentation/ and deployment shells into deployment/	2026-09-21 23:23:23 +00:00
embeddability.md	consolidate docs into documentation/ and deployment shells into deployment/	2026-09-21 23:23:23 +00:00
file-map.md	consolidate docs into documentation/ and deployment shells into deployment/	2026-09-21 23:23:23 +00:00
i18n.md	consolidate docs into documentation/ and deployment shells into deployment/	2026-09-21 23:23:23 +00:00
patterns-and-provenance.md	consolidate docs into documentation/ and deployment shells into deployment/	2026-09-21 23:23:23 +00:00
poster-generation.md	consolidate docs into documentation/ and deployment shells into deployment/	2026-09-21 23:23:23 +00:00
README.md	consolidate docs into documentation/ and deployment shells into deployment/	2026-09-21 23:23:23 +00:00

README.md

documentation/architecture/ — the deep end

Everything complex lives here, on purpose. The rest of the docs stay simple ("what it does"); when a simple doc says "full contract in architecture/…", this is where it points.

Doc	What it holds
file-map.md	every file, one line each, with the gotcha each carries
data-sources.md	the `api/` seam — connection contract + add-a-source checklist
color-strategies.md	the color-strategy contract + legend wiring
components.md	shared component catalog + shadow-DOM conventions
i18n.md	the locale contract + add-a-language checklist
embeddability.md	the generated per-map pages + manifest that make every map embeddable by default
app-wrappers.md	the SPA shell: `nav.js` + `PROFILES` contracts, `bun run shell` pipeline
poster-generation.md	the poster/preview generator pipeline
patterns-and-provenance.md	the two multi-map patterns in depth + where the design comes from

Simple docs: ../why.md · ../tutorial.md · ../how-to.md · ../reference.md · ../explanation.md