# Contributing to Chronicles of the Realm (江山时序)
English · 简体中文 (Chinese)
Thank you for your interest in **Chronicles of the Realm (`jiangshan-map`)**! This project aims to build a zero-dependency, historically rigorous interactive atlas of Chinese dynastic territories, administrative divisions, ancient cities, and historical journeys crafted in the aesthetic of traditional Chinese parchment cartography. We welcome contributions of all kinds, including: - **Historical & Geographic Corrections**: Fixing ancient place coordinates, refining prefecture/circuit evolution notes (`remark`), or adjusting dynastic phase transition years; - **Historical Milestones & Site-Specific Events**: Adding chronological milestones, capital relocations, or site-specific landmark events (`PLACE_LANDMARK_EVENTS`); - **Bilingual Translations & City Lore**: Improving English translations of historical proper nouns in [`js/i18n_dict.js`](js/i18n_dict.js) or expanding bilingual city epigraphs (`CITY_LORE`) in [`js/lore_detail.js`](js/lore_detail.js); - **UI/UX, Accessibility & Performance**: Enhancing mobile touch gestures, keyboard accessibility (ARIA), and SVG rendering performance. --- ## Repository Structure ```text ├── index.html # Main application page & semantic layout ├── llms.txt # Machine-readable protocol specification for LLMs & AI Agents ├── css/style.css # Traditional parchment theme & responsive styles ├── data/atlas/ # Editable source of the polygon bundles: one GeoJSON file per snapshot, grouped by dynasty, plus index.json ├── data/sources/ # References for milestones, events, journeys and people (not loaded by the site; milestone sources are derived into js/milestone_sources.js) ├── js/ │ ├── app.js # Core controller: Mercator projection, collision-free label layout, timeline, camera & DOM event wiring │ ├── atlas_trace.js # Place Genealogy (点地溯源), Person Chronicles (点人溯事), multi-person comparison & Historical Journeys module │ ├── atlas_search.js # Global Quick Search, Chinese Era & monarch parsing, event pinyin matching & ranking module │ ├── atlas_api.js # AI-Native Public API (resolvePlace / inspect / locate), multi-stop custom route, deep-link restore & WebMCP module │ ├── atlas_track.js # Anonymous button & feature click counter (deferred; batches counts to workers/stats, no cookies or personal data) │ ├── atlas_quiz.js # Lazy-loaded Ancient Place Pinpoint Quiz module (deck construction, clue sanitization, SVG scoring rings & action chip) │ ├── map_data.js # 18 historical periods metadata, phase rules, ancient settlements, milestones, rivers, passes & transport corridors │ ├── lore_core.js # First-paint & search lore: imperial eras (CHINESE_ERA_SPANS, REGIONAL_ERA_TRACKS), passes, gazetteer, person profiles & guqin tracks │ ├── lore_detail.js # Lazy-loaded lore detail: landmark events (PLACE_LANDMARK_EVENTS), biographical journeys, city lore (CITY_LORE) & polity profiles │ ├── zh_hant.js # Lazy-loaded Traditional Chinese (zh-Hant) runtime converter & historical polysemy dictionary │ ├── milestone_sources.js # Generated from data/sources/ by audit_sources.js --fix: lazy milestone source lines │ ├── atlas_boot.js # Generated from data/atlas/: initial snapshots for instant first-paint rendering │ ├── atlas_snapshots.js # Generated from data/atlas/: topology-deduplicated & VLQ delta-encoded polity/prefecture polygons (lazy-loaded on demand) │ ├── china_geo_data.js # VLQ delta-encoded modern provincial boundaries for the `Provinces` reference layer │ └── i18n_dict.js # Chinese-English dictionary for historical polities, prefectures, cities, and milestones ├── workers/stats/ # Cloudflare Worker behind stats.deanchen.me: write-only endpoint storing click counts in Workers Analytics Engine ├── skills/ │ └── jiangshan-atlas/ # Agent Skill (SKILL.md) & zero-dependency CLI screenshot/inspection tool (scripts/jiangshan.py) └── scripts/ ├── audit_prefectures.js # Zero-dependency prefecture-layer overlap / outside-polity audit against data/atlas/prefecture_baseline.json (--check in CI) ├── audit_sources.js # Zero-dependency reference audit for data/sources/ against data/sources/baseline.json (--check in CI) ├── audit_topology.js # Zero-dependency polity border gap/overlap audit against data/atlas/topology_baseline.json (--check in CI) ├── build_atlas.js # Zero-dependency builder: data/atlas/ → atlas_snapshots.js + atlas_boot.js (--check in CI) ├── check_sources.js # Zero-dependency local spot-check of data/sources/ references against the cited pages (needs network; not in CI) ├── perf_budget.js # Zero-dependency synchronous script gzip budget check against data/atlas/perf_baseline.json (--check in CI) ├── repair_topology.js # Zero-dependency border repair: snaps core polity borders together and rewrites data/atlas/ ├── sync_version.js # Zero-dependency per-asset SHA-256 cache-busting synchronizer for index.html └── validate_atlas.js # Zero-dependency automated data integrity, topology & E2E validation suite (--fast / full) ``` --- ## Local Development & Validation Workflow 1. **Clone and Serve Locally**: Built with vanilla ES6 and SVG with zero runtime dependencies—simply serve the repository root with any static HTTP server. No npm install is needed to serve the checked-in site: ```bash git clone https://github.com/DeanChensj/jiangshan-map.git cd jiangshan-map python3 -m http.server 8000 ``` Then open `http://localhost:8000` in your browser (or `http://localhost:8000/?lang=en` for English UI). 2. **Sync Per-Asset Cache-Busting Hashes (After Editing `css/` or `js/`)**: `index.html` stamps each CSS/JS bundle (and lazy-loaded bundle attributes on `#atlas-app-script`) with an 8-character SHA-256 content hash: ```bash node scripts/sync_version.js ``` 3. **Run the Automated Validation Suite**: During local iteration on UI, search, or data entries, use `--fast` for ~6-second feedback; before opening a Pull Request, run the full suite to also verify polygon topology, territorial exclusivity, and CLI/MCP smoke tests: ```bash node scripts/validate_atlas.js --fast # Fast check: syntax, hashes, schemas, i18n & UI CUJs node scripts/validate_atlas.js # Full suite: includes all polygon topology & subprocess checks ``` --- ### Rebuilding Event Pinyin Search Keys After editing milestone titles/sites in `js/map_data.js` or landmark titles/sites in `js/lore_detail.js`, regenerate the checked-in `js/event_pinyin.js`: ```bash npm ci --prefix scripts/search-pinyin --ignore-scripts --no-audit --no-fund npm run build --prefix scripts/search-pinyin npm run check --prefix scripts/search-pinyin npm test --prefix scripts/search-pinyin ``` The isolated build tool pins `pinyin-pro`; the browser loads the generated index on demand when searching. Rows follow the source event order, and CI rejects stale output after edits or reordering. Historical pronunciation overrides live in `scripts/search-pinyin/build.cjs`. Full or spaced pinyin, tone marks and `ü`/`v` are normalized only for the added event fallback (minimum four letters); Chinese/English, curated aliases and reign matching retain priority. Headline pinyin keys also span punctuation within titles. Exact pinyin keys rank ahead of partial pinyin matches. The normal atlas validation still runs without npm dependencies. ## Historical & Cartographic Conventions 1. **Ancient Settlements (`settlements` in `js/map_data.js`)**: - Coordinates follow `[longitude, latitude]` order (`WGS-84` / `CGCS2000`); - Hierarchy tiers: `isCapital: true` = imperial or regional regime capital; default (`tier` omitted) = major prefecture/circuit seat or strategic garrison; `tier: 2` = secondary prefecture or frontier outpost (progressively revealed on zoom); - If a settlement was founded, renamed, or abandoned mid-dynasty, specify `appear` and/or `vanish` years; - Every pre-modern settlement must include a concise historical `remark` (and its English translation in `js/i18n_dict.js`). 2. **Imperial Eras & Reigning Monarchs (`js/lore_core.js`)**: - Imperial era spans (`CHINESE_ERA_SPANS`) and regional era tracks (`REGIONAL_ERA_TRACKS`) reside in `js/lore_core.js` (while landmark events, journeys, city lore, and polity profiles reside in `js/lore_detail.js`). When adding or correcting reign dates, cross-check against standard chronological tables (*Zhongguo Lishi Jinian Biao*). - `CHINESE_ERA_SPANS` is the single reference chronology shown on the timeline and follows the *Zizhi Tongjian* convention (Cao Wei for the Three Kingdoms, Eastern Jin for the Sixteen Kingdoms, the Southern Dynasties for the Northern & Southern Dynasties, the Central Plains Five Dynasties, and Song alongside Liao/Jin/Xia). Co-existing regimes that kept their own eras (Shu Han, Sun Wu, the Northern Dynasties, Western Liang, Chen after 581, Liao, Jin, Western Xia, and Kublai's Yuan) live in `REGIONAL_ERA_TRACKS`; events are labeled with the era of the regime ruling their location. - If a milestone's subject is not the regime holding its pinned location (e.g. a Song–Jin treaty pinned on the Jin side of the border), set `"eraRegime": "reference"` or a `REGIONAL_ERA_TRACKS` regime name on that milestone in `js/map_data.js`. 3. **Historical Polities & Regional Boundaries (`data/atlas/`)**: - Edit the GeoJSON sources in `data/atlas/`, then rebuild. `js/atlas_snapshots.js` and `js/atlas_boot.js` are generated; do not edit them by hand. ```bash node scripts/build_atlas.js # Normalize formatting, rebuild both bundles, refresh index.html hashes node scripts/build_atlas.js --check # CI: sources formatted and bundles up to date ``` - Each snapshot is `data/atlas/