mapchart/ — Module Map for AI Agents

Single responsibility per file. Cross-module state lives in the orchestrator (../MapChart.vue) only. Read this before editing anything in this folder.

utils/ (pure TS, no Vue refs)

• color.ts ✓ — hex/RGB conversion, lerp, interpHex, choroplethRamp.
• geometry.ts ☐ — ptSegDist, bbox helpers, safeBounds, boxesIntersectOrTouch.
• svg-sanitize.ts ☐ — sanitizeSvgMarkup + tag/attribute allow-list + stroke override.
• format-parsers.ts ☐ — GeoJSON / TopoJSON / Shapefile / KML(Z) / CSV → normalized GeoJSON.
• projection-registry.ts ☐ — projection id → d3 factory + display label.
• name-disambiguation.ts ☐ — normName, abbrev index, neighbor disambiguation.
• state-schema.ts ☐ — FROZEN serialize/deserialize for autosave. Round-trip tested per fixture.
• viewport-math.ts ☐ — clampZoom, wheelFactorFromDelta, viewport↔shape coord conversion.

composables/ (Vue Composition API)

Rules:

• File ≤ 400 lines.
• Accept dependencies as parameters; never read other composables' module-level state.
• Return { state refs, computeds, actions }.
• Side effects (DOM, localStorage) go through injected handles, not direct globals.

Planned composables (one concern each): useHistory, useAutosave, useProjection, useMapData, useLegend, usePaint, useShapes, useLabels, useFeatureTransforms, useViewport, useKeyboard, useSvgLibrary, useDialogs, useOrientationTip.

ui/ (Vue SFCs)

Rules:

• Receive everything via props; emit user events. Do NOT import composables.
• Preserve existing class names verbatim — they are part of the test+CSS contract.
• Keep ARIA attributes and keyboard hints intact.

Drift log (track what diverged from guide/)

After Phase 0 the sync from ../guide/src/.vitepress/components/MapChart.vue is gone. Record any back-portable fix here so a future merge is tractable.

Date	Change	Reason
2026-04-16	Decoupled from sync; added test harness; extracted utils/color.ts	Refactor for AI manageability

Slice protocol (recap)

1. Extract → import back into MapChart.vue with // X moved to ... marker.
2. Add unit tests for new pure modules.
3. npm run test && npm run test:e2e — both must stay green.
4. Update the ✓ mark above.