krackedmaps 0.1.0

package/README.md

@@ -0,0 +1,149 @@
+# KrackedMaps · interactive map of Malaysia
+
+A self-contained, themeable SVG map of Malaysia — **16 admin-1 regions** (13 states +
+Kuala Lumpur, Putrajaya, Labuan) and **159 admin-2 *daerah*** — with **zero runtime
+dependencies**. Use it as a live component, a CLI, an MCP server for Claude, an embeddable
+iframe, or raw SVG / GeoJSON.
+
+**Customize & export:** https://map.themasterofnone.xyz · **Live demo:** https://map.themasterofnone.xyz/demo.html
+
+Two aligned layers from one shared projection: click a state to **drill in** (carve its
+districts + info panel); hover a district for its name; press Esc to step back out. East
+Malaysia is slid west to close the South China Sea gap for a compact frame.
+
+---
+
+## Three ways in
+
+```bash
+npm i krackedmaps          # library + CLI + MCP server, one package
+```
+
+### 1. Library (browser / SSR)
+
+```js
+import { createMalaysiaMap } from "krackedmaps";
+import "krackedmaps/css";
+
+const map = createMalaysiaMap("#map", { theme: "blueprint" });
+map.on("select", (slug) => console.log("selected", slug));
+```
+
+```js
+// server-side string builders (no DOM)
+import { renderSVG, project } from "krackedmaps";
+const svg = renderSVG({ theme: "blueprint", withDistricts: true });
+project(101.7117, 3.1578); // -> { x, y } in the SVG viewBox
+```
+
+### 2. CLI — grab assets from the terminal
+
+```bash
+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     # -> {"x":…,"y":…}
+npx krackedmaps states                       # list states
+npx krackedmaps --help
+```
+
+| command | output |
+|---|---|
+| `svg [--theme] [--districts] [--out]` | themed, self-contained SVG |
+| `geojson [--districts] [--out]` | GeoJSON (original lng/lat) |
+| `json [--out]` | projected paths + projection params |
+| `react [--theme] [--out]` | a `<MalaysiaMap>` component |
+| `embed [--theme] [--districts] [--labels] [--static]` | iframe snippet |
+| `project <lng> <lat>` | project real coords → SVG `{x,y}` |
+| `states` · `districts [--state <slug>]` · `themes` | listings |
+
+### 3. MCP server — use it inside Claude
+
+Exposes tools (`krackedmaps_svg`, `krackedmaps_geojson`, `krackedmaps_project`,
+`krackedmaps_states`, `krackedmaps_districts`, `krackedmaps_react`, `krackedmaps_embed`,
+`krackedmaps_paths`) so any Claude conversation can pull the map + data.
+
+**Claude Code:**
+```bash
+claude mcp add krackedmaps -- npx -y krackedmaps mcp
+```
+
+**Claude Desktop** (`claude_desktop_config.json`):
+```json
+{
+  "mcpServers": {
+    "krackedmaps": { "command": "npx", "args": ["-y", "krackedmaps", "mcp"] }
+  }
+}
+```
+
+Then ask Claude things like *"give me the Malaysia map as a blueprint SVG with districts"* or
+*"what SVG coordinate is KLCC?"*.
+
+---
+
+## `createMalaysiaMap(container, options)`
+
+`container` is an `HTMLElement` or selector. Returns an **instance** — make as many as you
+like; `destroy()` tears each one down cleanly.
+
+| option | default | description |
+|---|---|---|
+| `theme` | `"blueprint"` | preset (`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` | `true` | pointer / click / keyboard handlers |
+| `zoom` | `true` | zoom-to-state on select (`false` keeps the full map framed) |
+| `keyboard` | `true` | Escape steps back out (scoped, never global) |
+| `labels` | `false` | start with state labels shown |
+| `initialState` | `null` | slug to select after build |
+| `meta` / `colors` / `renderPanel` | — | per-state info / choropleth ramp / custom panel |
+
+```js
+map.select("penang"); map.focus("sabah"); map.drillInto("sarawak");
+map.addPin({ lng: 101.7117, lat: 3.1578, label: "KLCC" });
+map.setData({ penang: 1.8, sabah: 3.4 });   // choropleth by slug
+map.setTheme("batik"); map.toggleLabels(true);
+map.on("select" | "hover" | "drill", cb); map.off(name, cb);
+map.destroy();
+map.STATES; map.DISTRICTS; map.project(lng, lat);
+```
+
+## Theming
+
+Everything is CSS variables on the `.mmap` container — pass a `theme`, call `setTheme(...)`,
+or override in your own CSS. Key vars: `--sea`, `--land`, `--land-hover`, `--land-active`,
+`--stroke`, `--district`, `--carve`, `--district-hi`, `--label`, `--pin`, `--accent`.
+
+## Data only (no engine)
+
+```js
+import { STATES, DISTRICTS, project } from "krackedmaps/data";
+```
+
+Pre-generated files also live in [`exports/`](exports/) (served at `/exports/`): themed SVGs,
+normalized GeoJSON, projected-paths JSON. See [`exports/README.md`](exports/README.md).
+
+---
+
+## Develop
+
+```bash
+npm run dev      # python3 -m http.server 4173 — open http://localhost:4173
+npm run build    # bundle dist/ for npm (esbuild) + copy GeoJSON
+npm run bake     # re-run data/bake.py + data/export.py after changing source data
+```
+
+| file | role |
+|------|------|
+| `src/engine.js` | `createMalaysiaMap` — render + interaction engine |
+| `src/render.js` | pure SVG / snippet builders (shared by browser, CLI, MCP) |
+| `src/data.js` / `src/themes.js` | baked geometry re-export / theme presets |
+| `bin/cli.js` / `bin/mcp.js` | the CLI and the MCP server |
+| `data/states.js` | **baked** paths + `project()` (auto-generated — don't hand-edit) |
+| `index.html` / `playground.js` | the customize & export page (landing) |
+| `demo.html` / `demo.js` | the live demo (dogfoods the engine) |
+
+Provenance: states from codeforamerica/click_that_hood; districts (ADM2) + Labuan from
+geoBoundaries gbOpen (MYS). Check each source's license before commercial redistribution.
+MIT licensed.

package/bin/cli.js

@@ -0,0 +1,117 @@
+#!/usr/bin/env node
+// KrackedMaps CLI — grab Malaysia map assets straight from the terminal.
+import { readFileSync, writeFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import {
+  renderSVG, reactComponent, embedSnippet, project,
+  STATES, DISTRICTS, PROJECTION, PRESETS,
+} from "../dist/krackedmaps.esm.js";
+
+const VERSION = "0.1.0";
+const readGeo = (f) => readFileSync(fileURLToPath(new URL("../dist/" + f, import.meta.url)), "utf8");
+
+// crude flag parser → { _: [positional], flag: value | true }
+function parseArgs(argv) {
+  const out = { _: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a.startsWith("--")) {
+      const next = argv[i + 1];
+      if (next !== undefined && !next.startsWith("--")) { out[a.slice(2)] = next; i++; }
+      else out[a.slice(2)] = true;
+    } else out._.push(a);
+  }
+  return out;
+}
+
+function emit(text, args) {
+  if (typeof args.out === "string") {
+    writeFileSync(args.out, text.endsWith("\n") ? text : text + "\n");
+    process.stderr.write(`wrote ${args.out}\n`);
+  } else {
+    process.stdout.write(text.endsWith("\n") ? text : text + "\n");
+  }
+}
+
+function fail(msg) { process.stderr.write("krackedmaps: " + msg + "\n"); process.exit(1); }
+
+const HELP = `KrackedMaps ${VERSION} — interactive SVG map of Malaysia (16 states + 159 districts)
+
+Usage: krackedmaps <command> [options]
+
+Commands:
+  svg       [--theme <name>] [--districts] [--out <file>]            themed SVG
+  geojson   [--districts] [--out <file>]                             GeoJSON (lng/lat)
+  json      [--out <file>]                                           projected paths JSON
+  react     [--theme <name>] [--out <file>]                          React component
+  embed     [--theme <name>] [--districts] [--labels] [--static]     iframe snippet
+  project   <lng> <lat>                                              project coords -> {x,y}
+  states                                                             list states
+  districts [--state <slug>]                                         list districts
+  themes                                                             list theme presets
+  mcp                                                                start the MCP server (stdio)
+
+Themes: ${Object.keys(PRESETS).join(", ")}
+Docs:   https://map.themasterofnone.xyz`;
+
+async function main() {
+  const [cmd, ...rest] = process.argv.slice(2);
+  const args = parseArgs(rest);
+
+  switch (cmd) {
+    case undefined:
+    case "help": case "-h": case "--help":
+      console.log(HELP); break;
+    case "version": case "-v": case "--version":
+      console.log(VERSION); break;
+
+    case "svg":
+      emit(renderSVG({ withDistricts: !!args.districts, theme: args.theme || "blueprint" }), args); break;
+
+    case "geojson":
+      emit(readGeo(args.districts ? "krackedmaps-districts.geojson" : "krackedmaps.geojson"), args); break;
+
+    case "json":
+      emit(JSON.stringify({
+        projection: PROJECTION,
+        viewBox: `0 0 ${PROJECTION.viewW} ${PROJECTION.viewH}`,
+        states: STATES, districts: DISTRICTS,
+      }, null, args.out ? 0 : 2), args); break;
+
+    case "react":
+      emit(reactComponent(args.theme || "blueprint"), args); break;
+
+    case "embed":
+      emit(embedSnippet({
+        theme: args.theme || "blueprint",
+        districts: !!args.districts, labels: !!args.labels, static: !!args.static,
+      }), args); break;
+
+    case "project": {
+      const [lng, lat] = args._.map(Number);
+      if (!Number.isFinite(lng) || !Number.isFinite(lat))
+        fail("project needs <lng> <lat>, e.g. krackedmaps project 101.7117 3.1578");
+      console.log(JSON.stringify(project(lng, lat))); break;
+    }
+
+    case "states":
+      for (const s of STATES) console.log(`${s.slug}\t${s.name}\t${s.type}`); break;
+
+    case "districts": {
+      const list = args.state ? DISTRICTS.filter((d) => d.state === args.state) : DISTRICTS;
+      if (!list.length) fail(`no districts for state "${args.state}"`);
+      for (const d of list) console.log(`${d.state}/${d.slug}\t${d.name}`); break;
+    }
+
+    case "themes":
+      for (const name of Object.keys(PRESETS)) console.log(name); break;
+
+    case "mcp":
+      await import("./mcp.js"); break;
+
+    default:
+      fail(`unknown command "${cmd}". Run: krackedmaps --help`);
+  }
+}
+
+main().catch((e) => fail(e.message));

package/bin/mcp.js

@@ -0,0 +1,99 @@
+#!/usr/bin/env node
+// KrackedMaps MCP server — exposes the Malaysia map to Claude over stdio.
+// Zero-dependency, newline-delimited JSON-RPC 2.0 (MCP stdio transport).
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import {
+  renderSVG, reactComponent, embedSnippet, project,
+  STATES, DISTRICTS, PROJECTION, PRESETS,
+} from "../dist/krackedmaps.esm.js";
+
+const VERSION = "0.1.0";
+const readGeo = (f) => readFileSync(fileURLToPath(new URL("../dist/" + f, import.meta.url)), "utf8");
+const themeEnum = Object.keys(PRESETS);
+
+const TOOLS = [
+  { name: "krackedmaps_svg",
+    description: "Themed, self-contained SVG of Malaysia (16 states; optional 159 districts).",
+    inputSchema: { type: "object", properties: { theme: { type: "string", enum: themeEnum }, districts: { type: "boolean" } } },
+    run: (a) => renderSVG({ theme: a.theme || "blueprint", withDistricts: !!a.districts }) },
+  { name: "krackedmaps_geojson",
+    description: "GeoJSON FeatureCollection (original lng/lat) of states or districts, with normalized props.",
+    inputSchema: { type: "object", properties: { level: { type: "string", enum: ["states", "districts"] } } },
+    run: (a) => readGeo(a.level === "districts" ? "krackedmaps-districts.geojson" : "krackedmaps.geojson") },
+  { name: "krackedmaps_paths",
+    description: "Projected SVG paths + projection params (JSON) for custom rendering.",
+    inputSchema: { type: "object", properties: {} },
+    run: () => JSON.stringify({ projection: PROJECTION, viewBox: `0 0 ${PROJECTION.viewW} ${PROJECTION.viewH}`, states: STATES, districts: DISTRICTS }) },
+  { name: "krackedmaps_project",
+    description: "Project a real-world lng/lat to the map's SVG coordinates (pins land exactly).",
+    inputSchema: { type: "object", properties: { lng: { type: "number" }, lat: { type: "number" } }, required: ["lng", "lat"] },
+    run: (a) => JSON.stringify(project(Number(a.lng), Number(a.lat))) },
+  { name: "krackedmaps_states",
+    description: "List the 16 states/territories (slug, name, type).",
+    inputSchema: { type: "object", properties: {} },
+    run: () => JSON.stringify(STATES.map((s) => ({ slug: s.slug, name: s.name, type: s.type }))) },
+  { name: "krackedmaps_districts",
+    description: "List the 159 districts (optionally filtered by parent state slug).",
+    inputSchema: { type: "object", properties: { state: { type: "string" } } },
+    run: (a) => JSON.stringify((a.state ? DISTRICTS.filter((d) => d.state === a.state) : DISTRICTS).map((d) => ({ slug: d.slug, name: d.name, state: d.state }))) },
+  { name: "krackedmaps_react",
+    description: "A ready-to-paste React component using the krackedmaps npm package.",
+    inputSchema: { type: "object", properties: { theme: { type: "string", enum: themeEnum } } },
+    run: (a) => reactComponent(a.theme || "blueprint") },
+  { name: "krackedmaps_embed",
+    description: "An iframe embed snippet for the hosted, interactive map.",
+    inputSchema: { type: "object", properties: { theme: { type: "string", enum: themeEnum }, districts: { type: "boolean" } } },
+    run: (a) => embedSnippet({ theme: a.theme || "blueprint", districts: !!a.districts }) },
+];
+
+const send = (msg) => process.stdout.write(JSON.stringify(msg) + "\n");
+const reply = (id, result) => send({ jsonrpc: "2.0", id, result });
+const errReply = (id, code, message) => send({ jsonrpc: "2.0", id, error: { code, message } });
+
+function handle(msg) {
+  const { id, method, params } = msg;
+  switch (method) {
+    case "initialize":
+      return reply(id, {
+        protocolVersion: params?.protocolVersion || "2025-06-18",
+        capabilities: { tools: {} },
+        serverInfo: { name: "krackedmaps", version: VERSION },
+      });
+    case "notifications/initialized":
+    case "notifications/cancelled":
+      return; // notifications: no reply
+    case "ping":
+      return reply(id, {});
+    case "tools/list":
+      return reply(id, { tools: TOOLS.map(({ name, description, inputSchema }) => ({ name, description, inputSchema })) });
+    case "tools/call": {
+      const tool = TOOLS.find((t) => t.name === params?.name);
+      if (!tool) return errReply(id, -32602, `unknown tool: ${params?.name}`);
+      try {
+        return reply(id, { content: [{ type: "text", text: tool.run(params.arguments || {}) }] });
+      } catch (e) {
+        return reply(id, { content: [{ type: "text", text: "Error: " + e.message }], isError: true });
+      }
+    }
+    default:
+      if (id !== undefined) errReply(id, -32601, `method not found: ${method}`);
+  }
+}
+
+let buf = "";
+process.stdin.setEncoding("utf8");
+process.stdin.on("data", (chunk) => {
+  buf += chunk;
+  let nl;
+  while ((nl = buf.indexOf("\n")) >= 0) {
+    const line = buf.slice(0, nl).trim();
+    buf = buf.slice(nl + 1);
+    if (!line) continue;
+    let msg;
+    try { msg = JSON.parse(line); } catch { continue; }
+    try { handle(msg); } catch (e) { if (msg && msg.id !== undefined) errReply(msg.id, -32603, e.message); }
+  }
+});
+process.stdin.on("end", () => process.exit(0));
+process.stderr.write(`krackedmaps MCP server ${VERSION} ready (stdio)\n`);

package/dist/data.d.ts

@@ -0,0 +1,27 @@
+export interface Point { x: number; y: number; }
+
+export interface StateFeature {
+  slug: string;
+  name: string;
+  type: "state" | "ft";
+  d: string;
+  centroid: Point;
+}
+
+export interface DistrictFeature {
+  slug: string;
+  name: string;
+  state: string;
+  d: string;
+  centroid: Point;
+}
+
+export interface Projection {
+  minx: number; maxy: number; scale: number; pad: number; eastLng: number;
+  shift: number; offX: number; offY: number; viewW: number; viewH: number;
+}
+
+export const STATES: StateFeature[];
+export const DISTRICTS: DistrictFeature[];
+export const PROJECTION: Projection;
+export function project(lng: number, lat: number): Point;