<div align="center">

<img src="og.png" alt="KrackedMaps" width="560">

# KrackedMaps

Themeable SVG maps with zero runtime dependencies. Malaysia's 16 regions and 159
districts from one shared projection, plus a rotating globe and country maps. Use it
as a component, a CLI, an MCP server, or plain SVG and GeoJSON.

[![License: MIT](https://img.shields.io/badge/license-MIT-3a1f7a.svg)](LICENSE)
&nbsp;[![npm](https://img.shields.io/npm/v/krackedmaps?label=krackedmaps)](https://www.npmjs.com/package/krackedmaps)
&nbsp;[![Tests](https://github.com/enonforetsam/krackedmaps/actions/workflows/test.yml/badge.svg)](https://github.com/enonforetsam/krackedmaps/actions/workflows/test.yml)
&nbsp;[![Live](https://img.shields.io/badge/live-maps.krackeddevs.com-ff6b3d.svg)](https://maps.krackeddevs.com)

[Customize & export](https://maps.krackeddevs.com) ·
[Demo](https://maps.krackeddevs.com/demo.html) ·
[Docs](https://maps.krackeddevs.com/docs.html) ·
[Playground](https://maps.krackeddevs.com/playground.html)

</div>

## Install

```sh
npm i krackedmaps
```

```js
import { createMalaysiaMap } from "krackedmaps";
import "krackedmaps/css";

const map = createMalaysiaMap("#map", { theme: "blueprint" });
map.on("select", (slug) => console.log("selected", slug));
map.setData({ penang: 1.8, sabah: 3.4 });          // choropleth by slug
map.addPin({ lng: 101.7117, lat: 3.1578, label: "KLCC" });
```

Click a state to drill into its districts, hover a district for its name, Esc steps
back out. Make as many instances as you like; `destroy()` tears each one down.

Server-side, with no DOM:

```js
import { renderSVG, project } from "krackedmaps";
const svg = renderSVG({ theme: "batik", withDistricts: true });   // a string
project(101.7117, 3.1578);                                        // → { x, y }
```

Data only: `import { STATES, DISTRICTS, PROJECTION } from "krackedmaps/data"`.

## From the terminal

```sh
npx krackedmaps svg --theme blueprint --districts > malaysia.svg
npx krackedmaps geojson --districts > daerah.geojson
npx krackedmaps react --theme batik > MalaysiaMap.jsx
npx krackedmaps project 101.7117 3.1578          # KLCC → {"x":…,"y":…}
npx krackedmaps globe react --theme blueprint > Globe.jsx
npx krackedmaps --help
```

## Inside Claude

```sh
claude mcp add krackedmaps -- npx -y krackedmaps mcp
```

Then ask: "give me the Malaysia map as a blueprint SVG with districts", or "add a
rotating globe hero to this app". The MCP server exposes the SVG, GeoJSON, projection,
React and embed builders as tools.

## Globe and countries

```js
import { createGlobe, WORLD_COUNTRIES } from "krackedmaps/globe";
import "krackedmaps/globe.css";
const globe = createGlobe("#globe", { countries: WORLD_COUNTRIES, theme: "blueprint" });
```

Country maps beyond Malaysia are served by the hosted site
(`npx krackedmaps country japan embed`); see "What is open" below.

## Options

| option | default | description |
|---|---|---|
| `theme` | `"blueprint"` | `mono` · `flat-dark` · `light` · `blueprint` · `batik`, or `{ cssVar: value }` |
| `panel` / `tooltip` | `true` | built-in info panel / hover tooltip |
| `showDistricts` | `true` | district drill-down layer |
| `interactive` / `keyboard` | `true` | pointer, click and Esc handlers (scoped, never global) |
| `zoom` | `true` | zoom to a state on select |
| `labels` | `false` | start with state labels shown |
| `initialState` | `null` | slug to select after build |
| `meta` / `colors` / `renderPanel` | | per-state info, choropleth ramp, custom panel |

Methods: `select` · `focus` · `drillInto` · `addPin` · `setData` · `setTheme` ·
`toggleLabels` · `on` / `off` (`select`, `hover`, `drill`) · `destroy`.

## Data

Malaysia boundaries are geoBoundaries gbOpen (CC BY): ADM1 for the 16 regions, ADM2
for the 159 districts. World outlines are Natural Earth (public domain). Keep one
attribution line when you redistribute exports; the exporter writes it into the SVG's
`<metadata>`. Details and citation: [DATA-LICENSES.md](DATA-LICENSES.md).

## What is open, what is hosted

This package is the engine and the Malaysia data, MIT. maps.krackeddevs.com adds the
Poster Studio and the per-country atlas tiers, some of whose sources carry stricter
licences; those live in a separate repo and are served, not redistributed.

## Contributing

Data corrections with a source, new themes, and API improvements: see
[CONTRIBUTING.md](CONTRIBUTING.md).

## License

MIT © KrackedDevs