Light-year tools: letters to stars and a voyage clock

README.md

@@ -65,9 +65,32 @@ Where scripts aren't allowed (Notion, many blogs), use the iframe version; URL p
 <iframe src="https://interimm.org/mars-clock/embed/?lang=en&zone=5&rovers" title="Mars Clock" width="360" height="270" style="border:0"></iframe>
 ```
 
+## Light years
+
+[`lib/lightyear.js`](lib/lightyear.js) (one ES module, no dependencies) and the [Light Years page](https://interimm.org/mars-clock/en/lightyear/) ([中文](https://interimm.org/mars-clock/lightyear/)): letters to nearby stars that travel at light speed, and a voyage clock that compares years on Mars with years aboard. Units are light years and Julian years, so c = 1.
+
+```js
+import * as ly from 'https://cdn.jsdelivr.net/gh/InterImm/mars-clock@gh-pages/lib/lightyear.js';
+
+ly.voyage({ distance: 10.47, accel: 1 });           // 1 g to Epsilon Eridani, flip at the midpoint
+// { earthYears: 12.26, shipYears: 4.93, peakBeta: 0.988, peakGamma: 6.40, phases: [...], ... }
+ly.message(new Date(), ly.star('epsilon-eridani').distance, { replyAfter: 1 });
+// { sent, arrives, earliestReply, ... }
+ly.storyFromReal(new Date());                       // the InterImm story date (real + 70,491 days)
+```
+
+| Function | Returns |
+| --- | --- |
+| `voyage({ distance, accel, cruise, decelerate })` | Constant proper acceleration (g) to a cruise speed (fraction of c, or `null` to flip at the midpoint), coast, brake. Years in the Sun/Mars frame and aboard, peak speed, ideal photon-rocket mass ratio, phases. |
+| `voyageAt(v, t)` / `voyageDates(v, depart)` | Position, speed and ship clock `t` years after departure; arrival date and when news of it reaches home. |
+| `PROFILES`, `profileVoyage(id, distance)` | Ready-made ships: `sail`, `ark`, `fast`, `torch`. |
+| `message(sent, distance, { replyAfter })`, `messageProgress`, `emitted` | Light-speed message timing. |
+| `STARS`, `star(id)` | 14 nearby stars with distances in light years. |
+| `storyFromReal`, `realFromStory`, `STORY_OFFSET_DAYS` | The InterImm story calendar. |
+
 ## For AI assistants
 
-- **MCP server** (`mcp/server.mjs`, no dependencies, runs locally): `claude mcp add mars-time -- npx -y github:InterImm/mars-clock#gh-pages`, or `{"command": "npx", "args": ["-y", "github:InterImm/mars-clock#gh-pages"]}` in any MCP config. Tools: `get_mars_time`, `interimm_to_earth`, `mission_sol`, `sol_to_earth`, `mars_year_dates`.
+- **MCP server** (`mcp/server.mjs`, no dependencies, runs locally): `claude mcp add mars-time -- npx -y github:InterImm/mars-clock#gh-pages`, or `{"command": "npx", "args": ["-y", "github:InterImm/mars-clock#gh-pages"]}` in any MCP config. Tools: `get_mars_time`, `interimm_to_earth`, `mission_sol`, `sol_to_earth`, `mars_year_dates`, `light_message`, `interstellar_voyage`.
 - **Shell**: `npx -y github:InterImm/mars-clock#gh-pages now [--utc ISO] [--longitude deg_east] [--zone 0-24]` prints JSON.
 - **[llms.txt](llms.txt)** and **[llms-full.txt](llms-full.txt)** (the guide plus every formula and the library source; regenerated by `npm run build:api`).
 - **[OpenAPI](api/v1/openapi.json)** description of the JSON endpoints.
@@ -83,6 +106,7 @@ Static files, regenerated from the library by `npm run build:api` (CI fails if t
 | `api/v1/interimm-years.json` | Start and length of InterImm years 1–80, and the month names |
 | `api/v1/missions.json` | Landing times and longitudes |
 | `api/v1/leap-seconds.json` | The leap-second table |
+| `api/v1/stars.json` | Nearby stars, distance in light years, trip times for each ship profile |
 
 ```sh
 curl -s https://interimm.org/mars-clock/api/v1/daily/2026.json | jq '.rows[275]'

api/v1/index.json

@@ -1 +1 @@
-{"name":"InterImm Mars time API","version":"1.0.0","docs":"https://interimm.org/mars-clock/en/#api","library":"https://cdn.jsdelivr.net/gh/InterImm/mars-clock@gh-pages/lib/marstime.js","endpoints":{"daily":"daily/{year}.json for 2000-2050: one row per UTC day","marsYears":"mars-years.json","interimmYears":"interimm-years.json","missions":"missions.json","leapSeconds":"leap-seconds.json"},"openapi":"openapi.json","llms":"https://interimm.org/mars-clock/llms.txt","mcp":"npx -y github:InterImm/mars-clock#gh-pages"}
+{"name":"InterImm Mars time API","version":"1.0.0","docs":"https://interimm.org/mars-clock/en/#api","library":"https://cdn.jsdelivr.net/gh/InterImm/mars-clock@gh-pages/lib/marstime.js","endpoints":{"daily":"daily/{year}.json for 2000-2050: one row per UTC day","marsYears":"mars-years.json","interimmYears":"interimm-years.json","missions":"missions.json","leapSeconds":"leap-seconds.json","stars":"stars.json: nearby stars, light time and trip times"},"lightyear":"https://cdn.jsdelivr.net/gh/InterImm/mars-clock@gh-pages/lib/lightyear.js","openapi":"openapi.json","llms":"https://interimm.org/mars-clock/llms.txt","mcp":"npx -y github:InterImm/mars-clock#gh-pages"}

api/v1/openapi.json

@@ -1 +1 @@
-{"openapi":"3.1.0","info":{"title":"InterImm Mars time API","version":"1.0.0","description":"Static, precomputed Mars time tables (GET only, no key, CORS open). For an arbitrary instant use the JavaScript library (https://cdn.jsdelivr.net/gh/InterImm/mars-clock@gh-pages/lib/marstime.js) or the MCP server (npx -y github:InterImm/mars-clock#gh-pages). Guide for language models: https://interimm.org/mars-clock/llms.txt","license":{"name":"MIT","identifier":"MIT"}},"servers":[{"url":"https://interimm.org/mars-clock/api/v1"}],"paths":{"/daily/{year}.json":{"get":{"operationId":"getDailyTable","summary":"Mars time at 00:00 UTC on every day of an Earth year (2000-2050)","parameters":[{"name":"year","in":"path","required":true,"schema":{"type":"integer","minimum":2000,"maximum":2050}}],"responses":{"200":{"description":"Rows are arrays in the order of `columns`.","content":{"application/json":{"schema":{"type":"object","properties":{"about":{"type":"string"},"columns":{"type":"array","items":{"type":"string"},"example":["utc","msd","mtc","ls","marsYear","interimmDate","interimmClock","curiositySol","perseveranceSol"]},"rows":{"type":"array","items":{"type":"array","prefixItems":[{"type":"string","description":"UTC date"},{"type":"number","description":"Mars Sol Date"},{"type":"string","description":"Coordinated Mars Time hh:mm:ss"},{"type":"number","description":"Solar longitude Ls, degrees"},{"type":"integer","description":"Mars Year (Clancy)"},{"type":"string","description":"InterImm date year-MM-DD, zone 0"},{"type":"string","description":"InterImm clock, zone 0"},{"type":["integer","null"],"description":"Curiosity sol"},{"type":["integer","null"],"description":"Perseverance sol"}]}}}}}}}}}},"/mars-years.json":{"get":{"operationId":"getMarsYears","summary":"Start of Mars Years 1-80 and their Ls 90/180/270 dates","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"about":{"type":"string"},"years":{"type":"array","items":{"type":"object","properties":{"marsYear":{"type":"integer"},"start":{"type":"string"},"ls90":{"type":"string"},"ls180":{"type":"string"},"ls270":{"type":"string"}}}}}}}}}}}},"/interimm-years.json":{"get":{"operationId":"getInterimmYears","summary":"Start and length of InterImm calendar years 1-80, and month names","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"about":{"type":"string"},"months":{"type":"array","items":{"type":"object","properties":{"month":{"type":"integer"},"zh":{"type":"string"},"en":{"type":"string"}}}},"years":{"type":"array","items":{"type":"object","properties":{"year":{"type":"integer"},"start":{"type":"string"},"sols":{"type":"integer"}}}}}}}}}}}},"/missions.json":{"get":{"operationId":"getMissions","summary":"Landers and rovers: landing time (UTC) and longitude (degrees east)","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/leap-seconds.json":{"get":{"operationId":"getLeapSeconds","summary":"TAI-UTC table used for the conversion","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}}}}
+{"openapi":"3.1.0","info":{"title":"InterImm Mars time API","version":"1.0.0","description":"Static, precomputed Mars time tables (GET only, no key, CORS open). For an arbitrary instant use the JavaScript library (https://cdn.jsdelivr.net/gh/InterImm/mars-clock@gh-pages/lib/marstime.js) or the MCP server (npx -y github:InterImm/mars-clock#gh-pages). Guide for language models: https://interimm.org/mars-clock/llms.txt","license":{"name":"MIT","identifier":"MIT"}},"servers":[{"url":"https://interimm.org/mars-clock/api/v1"}],"paths":{"/daily/{year}.json":{"get":{"operationId":"getDailyTable","summary":"Mars time at 00:00 UTC on every day of an Earth year (2000-2050)","parameters":[{"name":"year","in":"path","required":true,"schema":{"type":"integer","minimum":2000,"maximum":2050}}],"responses":{"200":{"description":"Rows are arrays in the order of `columns`.","content":{"application/json":{"schema":{"type":"object","properties":{"about":{"type":"string"},"columns":{"type":"array","items":{"type":"string"},"example":["utc","msd","mtc","ls","marsYear","interimmDate","interimmClock","curiositySol","perseveranceSol"]},"rows":{"type":"array","items":{"type":"array","prefixItems":[{"type":"string","description":"UTC date"},{"type":"number","description":"Mars Sol Date"},{"type":"string","description":"Coordinated Mars Time hh:mm:ss"},{"type":"number","description":"Solar longitude Ls, degrees"},{"type":"integer","description":"Mars Year (Clancy)"},{"type":"string","description":"InterImm date year-MM-DD, zone 0"},{"type":"string","description":"InterImm clock, zone 0"},{"type":["integer","null"],"description":"Curiosity sol"},{"type":["integer","null"],"description":"Perseverance sol"}]}}}}}}}}}},"/mars-years.json":{"get":{"operationId":"getMarsYears","summary":"Start of Mars Years 1-80 and their Ls 90/180/270 dates","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"about":{"type":"string"},"years":{"type":"array","items":{"type":"object","properties":{"marsYear":{"type":"integer"},"start":{"type":"string"},"ls90":{"type":"string"},"ls180":{"type":"string"},"ls270":{"type":"string"}}}}}}}}}}}},"/interimm-years.json":{"get":{"operationId":"getInterimmYears","summary":"Start and length of InterImm calendar years 1-80, and month names","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"about":{"type":"string"},"months":{"type":"array","items":{"type":"object","properties":{"month":{"type":"integer"},"zh":{"type":"string"},"en":{"type":"string"}}}},"years":{"type":"array","items":{"type":"object","properties":{"year":{"type":"integer"},"start":{"type":"string"},"sols":{"type":"integer"}}}}}}}}}}}},"/missions.json":{"get":{"operationId":"getMissions","summary":"Landers and rovers: landing time (UTC) and longitude (degrees east)","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/stars.json":{"get":{"operationId":"getStars","summary":"Nearby stars: distance in light years and relativistic trip times per ship profile","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/leap-seconds.json":{"get":{"operationId":"getLeapSeconds","summary":"TAI-UTC table used for the conversion","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}}}}

api/v1/stars.json

@@ -0,0 +1 @@
+{"about":"Nearby stars: distance from the Sun in light years (= one-way light time in years, from Earth or Mars), and trip times for each ship profile in years (earthYears in the Sun/Mars frame, shipYears aboard).","storyOffsetDays":70491,"profiles":{"sail":{"name":{"en":"Light-sail probe (flyby)","zh":"光帆探测器（飞掠）"},"accel":1000,"cruise":0.2,"decelerate":false},"ark":{"name":{"en":"Fusion ark","zh":"聚变方舟"},"accel":0.05,"cruise":0.1,"decelerate":true},"fast":{"name":{"en":"Beamed sail, crewed","zh":"载人光帆"},"accel":0.3,"cruise":0.3,"decelerate":true},"torch":{"name":{"en":"Torch ship at 1 g","zh":"1 g 火炬船"},"accel":1,"cruise":null,"decelerate":true}},"stars":[{"id":"proxima","name":{"en":"Proxima Centauri","zh":"比邻星"},"distance":4.2465,"type":"M5.5V","planets":true,"voyages":{"sail":{"earthYears":21.2326,"shipYears":20.8036,"peakBeta":0.2},"ark":{"earthYears":44.4073,"shipYears":44.1977,"peakBeta":0.1},"fast":{"earthYears":15.1466,"shipYears":14.5104,"peakBeta":0.3},"torch":{"earthYears":5.8726,"shipYears":3.5421,"peakBeta":0.9497}}},{"id":"alpha-centauri","name":{"en":"Alpha Centauri A/B","zh":"南门二（半人马座α）"},"distance":4.37,"type":"G2V+K1V","voyages":{"sail":{"earthYears":21.8501,"shipYears":21.4086,"peakBeta":0.2},"ark":{"earthYears":45.6423,"shipYears":45.4265,"peakBeta":0.1},"fast":{"earthYears":15.5582,"shipYears":14.9031,"peakBeta":0.3},"torch":{"earthYears":6.0025,"shipYears":3.5824,"peakBeta":0.9517}}},{"id":"barnard","name":{"en":"Barnard's Star","zh":"巴纳德星"},"distance":5.96,"type":"M4V","planets":true,"voyages":{"sail":{"earthYears":29.8001,"shipYears":29.198,"peakBeta":0.2},"ark":{"earthYears":61.5423,"shipYears":61.2468,"peakBeta":0.1},"fast":{"earthYears":20.8582,"shipYears":19.9589,"peakBeta":0.3},"torch":{"earthYears":7.6561,"shipYears":4.0355,"peakBeta":0.9694}}},{"id":"wolf-359","name":{"en":"Wolf 359","zh":"沃尔夫359"},"distance":7.86,"type":"M6V","voyages":{"sail":{"earthYears":39.3001,"shipYears":38.5061,"peakBeta":0.2},"ark":{"earthYears":80.5423,"shipYears":80.1516,"peakBeta":0.1},"fast":{"earthYears":27.1916,"shipYears":26.0006,"peakBeta":0.3},"torch":{"earthYears":9.604,"shipYears":4.4638,"peakBeta":0.9803}}},{"id":"lalande-21185","name":{"en":"Lalande 21185","zh":"拉兰德21185"},"distance":8.31,"type":"M2V","planets":true,"voyages":{"sail":{"earthYears":41.5501,"shipYears":40.7106,"peakBeta":0.2},"ark":{"earthYears":85.0423,"shipYears":84.629,"peakBeta":0.1},"fast":{"earthYears":28.6916,"shipYears":27.4315,"peakBeta":0.3},"torch":{"earthYears":10.0626,"shipYears":4.5525,"peakBeta":0.982}}},{"id":"sirius","name":{"en":"Sirius","zh":"天狼星"},"distance":8.6,"type":"A1V+DA2","voyages":{"sail":{"earthYears":43.0001,"shipYears":42.1313,"peakBeta":0.2},"ark":{"earthYears":87.9423,"shipYears":87.5145,"peakBeta":0.1},"fast":{"earthYears":29.6582,"shipYears":28.3536,"peakBeta":0.3},"torch":{"earthYears":10.3578,"shipYears":4.6075,"peakBeta":0.983}}},{"id":"epsilon-eridani","name":{"en":"Epsilon Eridani","zh":"天苑四（波江座ε）"},"distance":10.47,"type":"K2V","planets":true,"voyages":{"sail":{"earthYears":52.3501,"shipYears":51.2924,"peakBeta":0.2},"ark":{"earthYears":106.6423,"shipYears":106.1207,"peakBeta":0.1},"fast":{"earthYears":35.8916,"shipYears":34.2998,"peakBeta":0.3},"torch":{"earthYears":12.2552,"shipYears":4.9287,"peakBeta":0.9877}}},{"id":"procyon","name":{"en":"Procyon","zh":"南河三"},"distance":11.46,"type":"F5IV+DQZ","voyages":{"sail":{"earthYears":57.3001,"shipYears":56.1424,"peakBeta":0.2},"ark":{"earthYears":116.5423,"shipYears":115.9711,"peakBeta":0.1},"fast":{"earthYears":39.1916,"shipYears":37.4478,"peakBeta":0.3},"torch":{"earthYears":13.2566,"shipYears":5.0791,"peakBeta":0.9895}}},{"id":"tau-ceti","name":{"en":"Tau Ceti","zh":"天仓五（鲸鱼座τ）"},"distance":11.91,"type":"G8V","planets":true,"voyages":{"sail":{"earthYears":59.5501,"shipYears":58.3469,"peakBeta":0.2},"ark":{"earthYears":121.0423,"shipYears":120.4486,"peakBeta":0.1},"fast":{"earthYears":40.6916,"shipYears":38.8787,"peakBeta":0.3},"torch":{"earthYears":13.7112,"shipYears":5.1438,"peakBeta":0.9902}}},{"id":"teegarden","name":{"en":"Teegarden's Star","zh":"蒂加登星"},"distance":12.5,"type":"M7V","planets":true,"voyages":{"sail":{"earthYears":62.5001,"shipYears":61.2373,"peakBeta":0.2},"ark":{"earthYears":126.9423,"shipYears":126.319,"peakBeta":0.1},"fast":{"earthYears":42.6582,"shipYears":40.7548,"peakBeta":0.3},"torch":{"earthYears":14.3068,"shipYears":5.2254,"peakBeta":0.991}}},{"id":"altair","name":{"en":"Altair","zh":"牛郎星（河鼓二）"},"distance":16.73,"type":"A7V","voyages":{"sail":{"earthYears":83.6501,"shipYears":81.96,"peakBeta":0.2},"ark":{"earthYears":169.2423,"shipYears":168.407,"peakBeta":0.1},"fast":{"earthYears":56.7582,"shipYears":54.2054,"peakBeta":0.3},"torch":{"earthYears":18.5666,"shipYears":5.7268,"peakBeta":0.9946}}},{"id":"vega","name":{"en":"Vega","zh":"织女星"},"distance":25.04,"type":"A0V","voyages":{"sail":{"earthYears":125.2001,"shipYears":122.6705,"peakBeta":0.2},"ark":{"earthYears":252.3423,"shipYears":251.0904,"peakBeta":0.1},"fast":{"earthYears":84.4582,"shipYears":80.6295,"peakBeta":0.3},"torch":{"earthYears":26.9078,"shipYears":6.4429,"peakBeta":0.9974}}},{"id":"trappist-1","name":{"en":"TRAPPIST-1","zh":"TRAPPIST-1"},"distance":40.66,"type":"M8V","planets":true,"voyages":{"sail":{"earthYears":203.3001,"shipYears":199.1926,"peakBeta":0.2},"ark":{"earthYears":408.5423,"shipYears":406.5074,"peakBeta":0.1},"fast":{"earthYears":136.5249,"shipYears":130.2979,"peakBeta":0.3},"torch":{"earthYears":42.5533,"shipYears":7.3294,"peakBeta":0.999}}},{"id":"betelgeuse","name":{"en":"Betelgeuse","zh":"参宿四"},"distance":548,"type":"M1-2Ia","note":"distance uncertain, 500-650 ly","voyages":{"sail":{"earthYears":2740.0001,"shipYears":2684.6409,"peakBeta":0.2},"ark":{"earthYears":5481.9423,"shipYears":5454.4767,"peakBeta":0.1},"fast":{"earthYears":1827.6582,"shipYears":1743.5363,"peakBeta":0.3},"torch":{"earthYears":549.934,"shipYears":12.2864,"peakBeta":1}}}]}