{"id":49721749,"url":"https://github.com/walktalkmeditate/pilgrim-viewer","last_synced_at":"2026-05-09T02:27:25.734Z","repository":{"id":346888704,"uuid":"1190830388","full_name":"walktalkmeditate/pilgrim-viewer","owner":"walktalkmeditate","description":"Open source browser-based viewer for .pilgrim and .gpx walk files. Your data stays on your device.","archived":false,"fork":false,"pushed_at":"2026-04-26T14:11:14.000Z","size":3238,"stargazers_count":1,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-26T15:24:09.658Z","etag":null,"topics":["gpx","gpx-viewer","mapbox","open-source","pilgrim","pilgrimage","privacy-first","typescript","vite","walking"],"latest_commit_sha":null,"homepage":"https://view.pilgrimapp.org","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/walktalkmeditate.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-24T16:56:58.000Z","updated_at":"2026-04-16T02:24:06.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/walktalkmeditate/pilgrim-viewer","commit_stats":null,"previous_names":["walktalkmeditate/pilgrim-viewer"],"tags_count":13,"template":false,"template_full_name":null,"purl":"pkg:github/walktalkmeditate/pilgrim-viewer","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/walktalkmeditate%2Fpilgrim-viewer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/walktalkmeditate%2Fpilgrim-viewer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/walktalkmeditate%2Fpilgrim-viewer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/walktalkmeditate%2Fpilgrim-viewer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/walktalkmeditate","download_url":"https://codeload.github.com/walktalkmeditate/pilgrim-viewer/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/walktalkmeditate%2Fpilgrim-viewer/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32804814,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-08T08:22:46.396Z","status":"online","status_checked_at":"2026-05-09T02:00:06.633Z","response_time":123,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["gpx","gpx-viewer","mapbox","open-source","pilgrim","pilgrimage","privacy-first","typescript","vite","walking"],"created_at":"2026-05-09T02:27:25.106Z","updated_at":"2026-05-09T02:27:25.720Z","avatar_url":"https://github.com/walktalkmeditate.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# *Pilgrim Viewer*\n\nOpen source browser-based viewer for `.pilgrim` and `.gpx` walk files.\nYour data stays on your device.\n\n**[view.pilgrimapp.org](https://view.pilgrimapp.org)**\n\n---\n\n## What it does\n\nDrop a `.gpx` file and see your route on a map with distance, duration, and elevation.\n\nDrop a `.pilgrim` file and see all of that *plus* your intention, weather, voice transcriptions, meditation timeline, celestial context, and a unique goshuin seal generated from the walk's data.\n\n**Same route. Completely different experience.** That gap is the point.\n\n## Features\n\n**Viewer**\n- Route map with activity-colored segments (walk/talk/meditate)\n- 10 data panels: Stats, Waypoints, Photos, Elevation, Timeline, Intention, Weather, Transcriptions, Celestial, Seal\n- Reliquary photo support — circular thumbnail markers at each pinned photo's GPS coordinate on the map, tap to expand. Sidebar Photos panel shows the same photos as a thumbnail grid; tap a thumbnail to fly the map to that location.\n- Walk list for multi-walk files\n- Collapsible panels, metric/imperial toggle\n\n**Overlay**\n- All walks layered on a dark map\n- Color by season or time of day\n- Walk timeline with clickable dates\n- Year in Review filter\n\n**Export**\n- PNG with stats footer\n- PNG clean (pure art, no text)\n- Combined journey goshuin seal watermark\n\n**Design**\n- Dark/light mode with lunar phase toggle\n- Wabi-sabi aesthetic (Cormorant Garamond + Lato)\n- Mobile responsive with bottom sheet sidebar\n- Animated calligraphy route background on home page\n\n## Try it\n\nVisit **[view.pilgrimapp.org](https://view.pilgrimapp.org)** and click a sample:\n\n| Route | GPX | Pilgrim |\n|-------|-----|---------|\n| Kumano Kodo, 5 days | `.gpx` | `.pilgrim` |\n| Camino de Santiago, 5 days | `.gpx` | `.pilgrim` |\n| Shikoku 88, 4 days | `.gpx` | `.pilgrim` |\n\nOr drop your own `.gpx` or `.pilgrim` file.\n\n## Editor\n\nThe same codebase serves a redactor / pruner at **edit.pilgrimapp.org**. Drop a `.pilgrim` or `.gpx` file, click **Tend**, and:\n\n- Archive whole walks (skeletal records preserve lifetime totals).\n- Delete sections, photos, voice recordings, pauses, activity segments.\n- Trim route start/end via map handles.\n- Edit intention, reflection, and voice-transcription text.\n\nAll client-side; nothing uploaded. The editor is hostname-gated — the view bundle at `view.pilgrimapp.org` does not load any edit code.\n\nLocal development:\n\n```bash\nnpm run dev\n# View mode (default):\nopen http://localhost:5173/\n# Edit mode (opt-in):\nopen http://localhost:5173/?edit=1\n```\n\nDeploy: identical to the viewer — same GitHub Action, tag-triggered. Add a CNAME for `edit.pilgrimapp.org` pointing at the same Pages site.\n\n## Development\n\n```bash\ngit clone git@github.com:walktalkmeditate/pilgrim-viewer.git\ncd pilgrim-viewer\nnpm install\n```\n\nCreate `.env.local` with your [Mapbox token](https://account.mapbox.com/access-tokens/):\n\n```\nVITE_MAPBOX_TOKEN=pk.your_token_here\n```\n\n```bash\nnpm run dev       # Start dev server at localhost:5173\nnpm run typecheck # TypeScript check\nnpm test          # Run 205 tests\nnpm run build     # Production build to dist/\n```\n\n## Stack\n\n| | |\n|---|---|\n| **Runtime** | Vanilla TypeScript, Vite, Mapbox GL JS, JSZip, fast-xml-parser |\n| **Tests** | Vitest (205 tests, 12 files) |\n| **Deploy** | GitHub Pages via GitHub Actions (tag-triggered) |\n| **Fonts** | Cormorant Garamond, Lato (Google Fonts) |\n\nNo framework. No state management library. No CSS framework. The viewer is a single-page app built with DOM APIs and canvas.\n\n## Architecture\n\n```\nsrc/\n  parsers/     .pilgrim and .gpx → normalized Walk type\n  map/         Mapbox renderers (single walk + overlay) + PNG export\n  panels/      8 data panels + goshuin seal\n  ui/          Drop zone, walk list, layout, route animation, toggles\n  main.ts      App entry — wires everything together\n```\n\nBoth parsers normalize into the same `Walk` type. Everything downstream is format-agnostic. Panels self-hide when their data is absent.\n\n## JS Bridge API\n\nFor embedding in a native app via WKWebView:\n\n```swift\nlet json = // serialize walks as .pilgrim JSON\nwebView.evaluateJavaScript(\"window.pilgrimViewer.loadData(\\(json))\")\n```\n\nAccepts `{ walks: [...], manifest?: {...} }` — same shapes as the `.pilgrim` ZIP contents. Data goes from CoreData to Swift to WKWebView JavaScript to rendered on screen. Nothing touches a server.\n\n## Privacy\n\nEverything runs in your browser. Your walk data is never uploaded, stored, or transmitted. The Mapbox token is used only to load map tiles. File parsing, rendering, and export all happen locally.\n\n## Related\n\n- [Pilgrim](https://pilgrimapp.org) — the iOS app that creates `.pilgrim` files\n\n## Sample photo credits\n\nThe three sample `.pilgrim` files in `public/samples/` embed photos from Wikimedia Commons to demonstrate the Walk Reliquary feature locally. All photos have been resized to ~600px max dimension and JPEG-compressed for thumbnail display. On-route coordinates are synthetic — each photo is placed at a plausible point along its sample walk, not at the original photographer's GPS.\n\n### Camino de Santiago (`camino-santiago.pilgrim`)\n\n- **Sarria medieval bridge** — Diego Delso — [CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/) — [Wikimedia](https://commons.wikimedia.org/wiki/File:Puente_medieval_sobre_el_r%C3%ADo_Celeiro,_Sarria,_Camino_de_Santiago,_Lugo,_Espa%C3%B1a,_2015-09-19,_DD_07.jpg)\n- **Yellow arrow waymark** — Mike T. Norton — [CC BY 2.0](https://creativecommons.org/licenses/by/2.0/) — [Wikimedia](https://commons.wikimedia.org/wiki/File:Camino_Sign.jpg)\n- **Portomarín bridge** — Carlos Delgado — [CC BY-SA 3.0](https://creativecommons.org/licenses/by-sa/3.0/) — [Wikimedia](https://commons.wikimedia.org/wiki/File:Portomar%C3%ADn-1.JPG)\n- **Gonzar kilometer marker** — Lameiro — [CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/) — [Wikimedia](https://commons.wikimedia.org/wiki/File:Portomar%C3%ADn_03-23b,_Gonzar.jpg)\n- **Ligonde wayside cross** — Satna — [CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/) — [Wikimedia](https://commons.wikimedia.org/wiki/File:Ligonde_LameirosAbaixo.jpg)\n- **Boente cross and fountain** — Simon Burchell — [CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/) — [Wikimedia](https://commons.wikimedia.org/wiki/File:Camino_Franc%C3%A9s,_Boente_02.jpg)\n- **Galician landscape near Arzúa** — Simon Burchell — [CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/) — [Wikimedia](https://commons.wikimedia.org/wiki/File:Paisaje,_Camino_Franc%C3%A9s,_Arz%C3%BAa,_Galicia.jpg)\n- **Monte do Gozo monument** — Simon Burchell — [CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/) — [Wikimedia](https://commons.wikimedia.org/wiki/File:Monumento_de_Monte_do_Gozo,_Santiago_de_Compostela.jpg)\n- **Santiago de Compostela cathedral** — Lmbuga — [CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/) — [Wikimedia](https://commons.wikimedia.org/wiki/File:2025_Facade_towers_of_the_Cathedral_of_Santiago_from_the_Garden_of_the_Speaking_Stones._Galicia.jpg)\n\n### Kumano Kodo Nakahechi (`kumano-kodo.pilgrim`)\n\n- **Hosshinmon-oji shrine gate** — Nekosuki — [CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/) — [Wikimedia](https://commons.wikimedia.org/wiki/File:Hosshinmon_oji.JPG)\n- **Moss-lined stone stairway (Nakahechi route)** — VKaeru — [CC BY-SA 3.0](https://creativecommons.org/licenses/by-sa/3.0/) — [Wikimedia](https://commons.wikimedia.org/wiki/File:Kumano_Kodo_stairs.jpg)\n- **Gyuba-doji stone statue** — Vindlys — [CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/) — [Wikimedia](https://commons.wikimedia.org/wiki/File:Kumano_Kodo_Gyuba_Doji_2.jpg)\n- **Kumano Hongu Taisha main sanctuary** — Zairon — [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) — [Wikimedia](https://commons.wikimedia.org/wiki/File:Tanabe_Kumano_Hongu-Taisha_Honden_Hongu_1.jpg)\n- **Kumano Hongu Taisha stone lanterns** — Zairon — [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) — [Wikimedia](https://commons.wikimedia.org/wiki/File:Tanabe_Kumano_Hongu-Taisha_Lanterns.jpg)\n- **Kumano Nachi Taisha vermillion halls** — Suikotei — [CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/) — [Wikimedia](https://commons.wikimedia.org/wiki/File:Kumano_Nachi_Taisha_201908-2.jpg)\n- **Kumano Nachi Taisha courtyard** — Zairon — [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) — [Wikimedia](https://commons.wikimedia.org/wiki/File:Nachikatsuura_Kumano-Nachi-taisha_Courtyard_1.jpg)\n- **Nachi Falls with Seiganto-ji pagoda** — Douglas Perkins — [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) — [Wikimedia](https://commons.wikimedia.org/wiki/File:Nachi_Waterfall_in_Winter_01.jpg)\n\n### Shikoku 88 Temples 1–9 (`shikoku-88.pilgrim`)\n\n- **Ryozenji (Temple 1) tahoto pagoda** — Soramimi — [CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/) — [Wikimedia](https://commons.wikimedia.org/wiki/File:Tahoto_Pagoda_of_Ryozenji_Temple.jpg)\n- **Ryozenji (Temple 1) main hall** — Soramimi — [CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/) — [Wikimedia](https://commons.wikimedia.org/wiki/File:Hondo_Hall_of_Ryozenji_Temple.jpg)\n- **Gokurakuji (Temple 2) gate** — Reggaeman — [CC BY-SA 3.0](https://creativecommons.org/licenses/by-sa/3.0/) — [Wikimedia](https://commons.wikimedia.org/wiki/File:Nisshozan_Gokurakuji_01.JPG)\n- **Konsenji (Temple 3) stone-lantern courtyard** — Reggaeman — [CC BY-SA 3.0](https://creativecommons.org/licenses/by-sa/3.0/) — [Wikimedia](https://commons.wikimedia.org/wiki/File:Konsenji_02.JPG)\n- **Dainichiji (Temple 4) gate** — Reggaeman — [CC BY-SA 3.0](https://creativecommons.org/licenses/by-sa/3.0/) — [Wikimedia](https://commons.wikimedia.org/wiki/File:Dainichiji,_Tokushima_05.JPG)\n- **Anrakuji (Temple 6) main hall** — Naokijp — [CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/) — [Wikimedia](https://commons.wikimedia.org/wiki/File:Anraku-ji,_Main_Hall_01.jpg)\n- **Horinji (Temple 9) sanmon gate** — Reggaeman — [CC BY-SA 3.0](https://creativecommons.org/licenses/by-sa/3.0/) — [Wikimedia](https://commons.wikimedia.org/wiki/File:Shokakuzan_Horinji_01.JPG)\n\n## License\n\nThe viewer source code is [MIT](LICENSE). Sample photo credits as listed above.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwalktalkmeditate%2Fpilgrim-viewer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwalktalkmeditate%2Fpilgrim-viewer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwalktalkmeditate%2Fpilgrim-viewer/lists"}