@gooddadmike/ifc-js 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+All notable changes to `ifc-js` will be documented here.
+
+> This library's core calendar math originated in
+> [pebble-ifc-complication](https://github.com/gooddadmike/pebble-ifc-complication),
+> a Pebble watch widget package. It was extracted, corrected, and
+> published here as a standalone universal library. For pre-extraction
+> history see that repo's commit log.
+
+## [1.0.0] - 2026-03-22
+### Added
+- `toIFC(date?)` — Gregorian ISO string or Date to IFC result object
+- `toGregorian(ifcString)` — IFC: prefixed string to Gregorian ISO string
+- `isLeap(year)` — leap year utility export
+- CLI via `ifc` command — no args for today, accepts Gregorian or IFC: strings
+- CommonJS and ES module exports
+- Full Jest test suite covering edge cases, special days, and round trips
+
+### Fixed
+- DST off-by-one: date strings parsed manually via split('-') rather than
+  new Date() to avoid 1-hour spring-forward causing wrong day-of-year
+- Leap Day correctly at doy 169, not 181
+- All months after Sol correctly offset by 1 in leap years
+

package/CONTRIBUTING.md

@@ -0,0 +1,45 @@
+# Contributing
+
+Pull requests are welcome. A few guidelines:
+
+## Core IFC rules — do not change lightly
+The IFC math follows the standard Cotsworth/Eastman specification:
+- 13 months x 28 days
+- Leap Day inserted after June 28 (doy 169) in leap years only
+- Year Day is the last day of the year (doy 365 or 366)
+- Every month starts on Sunday, ends on Saturday
+- Leap Day and Year Day have no weekday
+
+Any PR that changes this behavior needs a very compelling reason and
+must update the test suite accordingly.
+
+## Adding features
+- New config options should be additive and not break existing behavior
+- `toIFC()` must always return a complete result object, don't change the shape
+- New output formats go in a `format` option, not as separate functions
+- Locale and language support is welcome, add to a `locale` option
+
+## Code style
+- Keep it simple, this is intentionally a zero-dependency library
+- Pure functions only in `src/index.js`, no side effects
+- Tests for every new behavior in `tests/ifc.test.js`
+- Run `npm test` before submitting, all tests must pass
+
+## Adding tests
+- Edge cases around Leap Day and Year Day are especially important
+- Round trip tests (Gregorian to IFC to Gregorian) for any new date paths
+- If you find a date that converts incorrectly, add a failing test first
+
+## What we would love to see
+- Locale and language support for month and weekday names
+- A `format` option for controlling output string style
+- Additional CLI flags
+
+## What to avoid
+- Changing the `IFC:` prefix format, it exists to prevent ambiguity
+- Returning raw strings from `toIFC()`, the result object is intentional
+- Adding dependencies to the main package
+
+## License
+
+MIT

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mike searcy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,165 @@
+# ifc-js
+
+A lightweight JavaScript library for converting dates between the Gregorian
+calendar and the International Fixed Calendar (IFC).
+
+## What is the International Fixed Calendar?
+
+The Gregorian calendar has months of 28, 29, 30, and 31 days so your
+birthday falls on a different weekday every year and nothing lines up
+neatly. The International Fixed Calendar fixes this.
+
+13 months x 28 days = 364 days. Every date falls on the same weekday every
+year. Your birthday is always on the same day of the week. The first of every
+month is always a Sunday. Most civil holidays stay put.
+
+Got something you do every other day? Water the plants, take a supplement,
+whatever it is. With IFC you can just look at the date number and know. With
+Gregorian, months can end on an odd day so you would have to skip a day just
+to stay on schedule. IFC months always end on day 28. No skipping. Ever.
+
+Months: Jan, Feb, Mar, Apr, May, Jun, **Sol**, Jul, Aug, Sep, Oct, Nov, Dec
+
+### Bonus Days
+
+The remaining day (or two in a leap year) becomes something more interesting
+than just another Tuesday. These intercalary days sit at the end of their
+month like a 29th day but belong to no week and no weekday.
+
+- 🎆 **Year Day** (Dec 29) — after the last day of December every year.
+  New Year's Eve elevated: a day outside the week, a pause between years.
+- ☀️ **Leap Day** (Jun 29) — after June 28 in leap years only. In any
+  normal IFC month, day 28 is a Saturday. Instead of a lost Sunday, this
+  becomes a once every four years midsummer holiday outside the week entirely.
+
+---
+
+## Install
+```bash
+npm install ifc-js
+```
+
+For the CLI:
+```bash
+npm install -g ifc-js
+```
+
+---
+
+## CLI
+```bash
+# Today's date in IFC
+ifc
+
+# Gregorian to IFC
+ifc 2024-06-17
+
+# IFC to Gregorian
+ifc IFC:2024-06-29
+```
+
+Output:
+```
+IFC:2026-03-25
+IFC:2024-06-29
+2024-06-17
+```
+
+---
+
+## API
+
+### `toIFC(date?)`
+
+Converts a Gregorian date to an IFC result object.
+```js
+const { toIFC } = require('ifc-js');
+
+toIFC('2026-03-22');
+// {
+//   year: 2026,
+//   month: 3,
+//   day: 25,
+//   weekday: 4,       // 0=Sun, 1=Mon ... 6=Sat
+//   isLeapDay: false,
+//   isYearDay: false
+// }
+
+toIFC('2024-06-17');
+// { year: 2024, month: 6, day: 29, weekday: null, isLeapDay: true, isYearDay: false }
+
+toIFC('2026-12-31');
+// { year: 2026, month: 13, day: 29, weekday: null, isLeapDay: false, isYearDay: true }
+
+// No argument uses today
+toIFC();
+```
+
+Months are 1-based: 1=January, 7=Sol, 13=December.
+`weekday` is `null` for Leap Day and Year Day as they have no weekday.
+
+---
+
+### `toGregorian(ifcString)`
+
+Converts an IFC date string to a Gregorian ISO date string.
+```js
+const { toGregorian } = require('ifc-js');
+
+toGregorian('IFC:2024-06-29');  // '2024-06-17'  (Leap Day)
+toGregorian('IFC:2026-07-01');  // '2026-06-18'  (Sol 1)
+toGregorian('IFC:2026-13-29');  // '2026-12-31'  (Year Day)
+```
+
+---
+
+### `isLeap(year)`
+
+Returns `true` if the given year is a leap year.
+```js
+const { isLeap } = require('ifc-js');
+
+isLeap(2024);  // true
+isLeap(2026);  // false
+isLeap(1900);  // false
+isLeap(2000);  // true
+```
+
+---
+
+### ES Modules
+```js
+import { toIFC, toGregorian, isLeap } from 'ifc-js';
+```
+
+---
+
+## IFC Date Format
+
+IFC dates must use the `IFC:` prefix. Without it the parser assumes
+Gregorian. This is not optional. The same numeric string means different
+things in each calendar:
+```
+2024-07-15       -> Gregorian July 15
+IFC:2024-07-15   -> IFC Sol 15 (Gregorian July 2nd)
+```
+
+IFC month numbers are 1-based and go up to 13:
+
+| Number | Month   |
+|--------|---------|
+| 1 - 6  | Jan-Jun |
+| 7      | Sol     |
+| 8 - 13 | Jul-Dec |
+
+---
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+---
+
+## License
+
+MIT

package/bin/ifc.js

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+'use strict';
+
+const { toIFC, toGregorian } = require('../src/index.js');
+
+const pad = n => String(n).padStart(2, '0');
+const fmt = r => `IFC:${r.year}-${pad(r.month)}-${pad(r.day)}`;
+
+const arg = process.argv[2];
+
+try {
+  if (!arg) {
+    console.log(fmt(toIFC()));
+  } else if (arg.startsWith('IFC:')) {
+    console.log(toGregorian(arg));
+  } else {
+    console.log(fmt(toIFC(arg)));
+  }
+} catch (err) {
+  console.error(`Error: ${err.message}`);
+  process.exit(1);
+}
+

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@gooddadmike/ifc-js",
+  "version": "1.0.0",
+  "description": "International Fixed Calendar conversion library — Gregorian to IFC and back",
+  "main": "src/index.js",
+  "module": "src/index.esm.js",
+  "exports": {
+    "require": "./src/index.js",
+    "import": "./src/index.esm.js"
+  },
+  "bin": {
+    "ifc": "./bin/ifc.js"
+  },
+  "scripts": {
+    "test": "jest"
+  },
+  "keywords": [
+    "ifc",
+    "international-fixed-calendar",
+    "calendar",
+    "date",
+    "cotsworth"
+  ],
+  "author": "mike@searcy.me",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/gooddadmike/ifc-js.git"
+  },
+  "bugs": {
+    "url": "https://github.com/gooddadmike/ifc-js/issues"
+  },
+  "homepage": "https://github.com/gooddadmike/ifc-js#readme",
+  "devDependencies": {
+    "jest": "^30.3.0"
+  }
+}

package/src/index.esm.js

@@ -0,0 +1,88 @@
+// ─── Month names ──────────────────────────────────────────────────────────────
+const IFC_MONTHS  = ['Jan','Feb','Mar','Apr','May','Jun',
+                     'Sol','Jul','Aug','Sep','Oct','Nov','Dec'];
+const GREG_MONTHS = ['Jan','Feb','Mar','Apr','May','Jun',
+                     'Jul','Aug','Sep','Oct','Nov','Dec'];
+const WEEKDAYS    = ['Sun','Mon','Tue','Wed','Thu','Fri','Sat'];
+
+// ─── Core utilities ───────────────────────────────────────────────────────────
+function isLeap(year) {
+  return (year % 4 === 0 && year % 100 !== 0) || year % 400 === 0;
+}
+
+function gregToDoy(year, month0, day) {
+  const dim = [31, isLeap(year)?29:28, 31,30,31,30,31,31,30,31,30,31];
+  let doy = day;
+  for (let i = 0; i < month0; i++) doy += dim[i];
+  return doy;
+}
+
+function doyToGreg(year, doy) {
+  const dim = [31, isLeap(year)?29:28, 31,30,31,30,31,31,30,31,30,31];
+  let rem = doy;
+  for (let m = 0; m < 12; m++) {
+    if (rem <= dim[m]) return { month: m, day: rem };
+    rem -= dim[m];
+  }
+}
+
+function ifcToDoy(year, mi, day) {
+  // mi is 1-based (1=Jan ... 7=Sol ... 13=Dec)
+  if (mi === 6 && day === 29 && isLeap(year)) return 169;
+  let doy = (mi - 1) * 28 + day;
+  if (mi > 6 && isLeap(year)) doy += 1;
+  return doy;
+}
+
+function doyToIfc(year, doy) {
+  const leap    = isLeap(year);
+  const yearLen = leap ? 366 : 365;
+  if (leap && doy === 169)  return { month: 6,  day: 29, weekday: null, isLeapDay: true,  isYearDay: false };
+  if (doy === yearLen)      return { month: 13, day: 29, weekday: null, isLeapDay: false, isYearDay: true  };
+  const adjDoy  = leap && doy > 169 ? doy - 1 : doy;
+  const mi      = Math.floor((adjDoy - 1) / 28) + 1;  // 1-based
+  const day     = (adjDoy - 1) % 28 + 1;
+  const weekday = (day - 1) % 7;                       // 0=Sun ... 6=Sat
+  return { month: mi, day, weekday, isLeapDay: false, isYearDay: false };
+}
+
+// ─── Public API ───────────────────────────────────────────────────────────────
+function toIFC(input, options = {}) {
+  let year, month0, day;
+  if (input) {
+    const [y, m, d] = String(input).split('-').map(Number);
+    year   = y;
+    month0 = m - 1;
+    day    = d;
+    if (isNaN(year) || isNaN(month0) || isNaN(day)) throw new Error(`Invalid date: ${input}`);
+  } else {
+    const now = new Date();
+    year   = now.getFullYear();
+    month0 = now.getMonth();
+    day    = now.getDate();
+  }
+  const doy = gregToDoy(year, month0, day);
+  return { year, ...doyToIfc(year, doy) };
+}
+
+function toGregorian(ifcString) {
+  if (!ifcString.startsWith('IFC:')) {
+    throw new Error('IFC dates must be prefixed with "IFC:" e.g. IFC:2024-07-15');
+  }
+  const parts = ifcString.slice(4).split('-').map(Number);
+  const [year, month, day] = parts;
+  if (!year || !month || !day) throw new Error(`Invalid IFC date format: ${ifcString}`);
+  if (month < 1 || month > 13) throw new Error(`IFC month must be 1-13, got ${month}`);
+  if (day < 1 || day > 29)     throw new Error(`IFC day must be 1-29, got ${day}`);
+  if (day === 29) {
+    if (month === 6 && !isLeap(year)) throw new Error(`Leap Day only exists in leap years`);
+    if (month !== 6 && month !== 13)  throw new Error(`Day 29 only valid for June (leap years) or December`);
+  }
+  const doy  = ifcToDoy(year, month, day);
+  const g    = doyToGreg(year, doy);
+  const date = new Date(year, g.month, g.day);
+  return date.toISOString().split('T')[0];
+}
+
+export { toIFC, toGregorian, isLeap };
+

package/src/index.js

@@ -0,0 +1,89 @@
+'use strict';
+
+// ─── Month names ──────────────────────────────────────────────────────────────
+const IFC_MONTHS  = ['Jan','Feb','Mar','Apr','May','Jun',
+                     'Sol','Jul','Aug','Sep','Oct','Nov','Dec'];
+const GREG_MONTHS = ['Jan','Feb','Mar','Apr','May','Jun',
+                     'Jul','Aug','Sep','Oct','Nov','Dec'];
+const WEEKDAYS    = ['Sun','Mon','Tue','Wed','Thu','Fri','Sat'];
+
+// ─── Core utilities ───────────────────────────────────────────────────────────
+function isLeap(year) {
+  return (year % 4 === 0 && year % 100 !== 0) || year % 400 === 0;
+}
+
+function gregToDoy(year, month0, day) {
+  const dim = [31, isLeap(year)?29:28, 31,30,31,30,31,31,30,31,30,31];
+  let doy = day;
+  for (let i = 0; i < month0; i++) doy += dim[i];
+  return doy;
+}
+
+function doyToGreg(year, doy) {
+  const dim = [31, isLeap(year)?29:28, 31,30,31,30,31,31,30,31,30,31];
+  let rem = doy;
+  for (let m = 0; m < 12; m++) {
+    if (rem <= dim[m]) return { month: m, day: rem };
+    rem -= dim[m];
+  }
+}
+
+function ifcToDoy(year, mi, day) {
+  // mi is 1-based (1=Jan ... 7=Sol ... 13=Dec)
+  if (mi === 6 && day === 29 && isLeap(year)) return 169;
+  let doy = (mi - 1) * 28 + day;
+  if (mi > 6 && isLeap(year)) doy += 1;
+  return doy;
+}
+
+function doyToIfc(year, doy) {
+  const leap    = isLeap(year);
+  const yearLen = leap ? 366 : 365;
+  if (leap && doy === 169)  return { month: 6,  day: 29, weekday: null, isLeapDay: true,  isYearDay: false };
+  if (doy === yearLen)      return { month: 13, day: 29, weekday: null, isLeapDay: false, isYearDay: true  };
+  const adjDoy  = leap && doy > 169 ? doy - 1 : doy;
+  const mi      = Math.floor((adjDoy - 1) / 28) + 1;  // 1-based
+  const day     = (adjDoy - 1) % 28 + 1;
+  const weekday = (day - 1) % 7;                       // 0=Sun ... 6=Sat
+  return { month: mi, day, weekday, isLeapDay: false, isYearDay: false };
+}
+
+// ─── Public API ───────────────────────────────────────────────────────────────
+function toIFC(input, options = {}) {
+  let year, month0, day;
+  if (input) {
+    const [y, m, d] = String(input).split('-').map(Number);
+    year   = y;
+    month0 = m - 1;
+    day    = d;
+    if (isNaN(year) || isNaN(month0) || isNaN(day)) throw new Error(`Invalid date: ${input}`);
+  } else {
+    const now = new Date();
+    year   = now.getFullYear();
+    month0 = now.getMonth();
+    day    = now.getDate();
+  }
+  const doy = gregToDoy(year, month0, day);
+  return { year, ...doyToIfc(year, doy) };
+}
+
+function toGregorian(ifcString) {
+  if (!ifcString.startsWith('IFC:')) {
+    throw new Error('IFC dates must be prefixed with "IFC:" e.g. IFC:2024-07-15');
+  }
+  const parts = ifcString.slice(4).split('-').map(Number);
+  const [year, month, day] = parts;
+  if (!year || !month || !day) throw new Error(`Invalid IFC date format: ${ifcString}`);
+  if (month < 1 || month > 13) throw new Error(`IFC month must be 1-13, got ${month}`);
+  if (day < 1 || day > 29)     throw new Error(`IFC day must be 1-29, got ${day}`);
+  if (day === 29) {
+    if (month === 6 && !isLeap(year)) throw new Error(`Leap Day only exists in leap years`);
+    if (month !== 6 && month !== 13)  throw new Error(`Day 29 only valid for June (leap years) or December`);
+  }
+  const doy  = ifcToDoy(year, month, day);
+  const g    = doyToGreg(year, doy);
+  const date = new Date(year, g.month, g.day);
+  return date.toISOString().split('T')[0];
+}
+
+module.exports = { toIFC, toGregorian, isLeap };

package/tests/ifc.test.js

@@ -0,0 +1,166 @@
+'use strict';
+const { toIFC, toGregorian, isLeap } = require('../src/index.js');
+
+// ─── isLeap ───────────────────────────────────────────────────────────────────
+describe('isLeap', () => {
+  test('2024 is a leap year', () => expect(isLeap(2024)).toBe(true));
+  test('2023 is not a leap year', () => expect(isLeap(2023)).toBe(false));
+  test('1900 is not a leap year (div by 100)', () => expect(isLeap(1900)).toBe(false));
+  test('2000 is a leap year (div by 400)', () => expect(isLeap(2000)).toBe(true));
+});
+
+// ─── toIFC ────────────────────────────────────────────────────────────────────
+describe('toIFC', () => {
+  test('normal date — Mar 22 2026', () => {
+    expect(toIFC('2026-03-22')).toMatchObject({
+      year: 2026, month: 3, day: 25, isLeapDay: false, isYearDay: false
+    });
+  });
+
+  test('first day of Sol — 2026', () => {
+    expect(toIFC('2026-06-18')).toMatchObject({
+      year: 2026, month: 7, day: 1, isLeapDay: false, isYearDay: false
+    });
+  });
+
+  test('Leap Day — 2024', () => {
+    expect(toIFC('2024-06-17')).toMatchObject({
+      year: 2024, month: 6, day: 29, isLeapDay: true, isYearDay: false, weekday: null
+    });
+  });
+
+  test('day before Leap Day is Jun 28 — 2024', () => {
+    expect(toIFC('2024-06-16')).toMatchObject({
+      year: 2024, month: 6, day: 28, isLeapDay: false, isYearDay: false, weekday: 6
+    });
+  });
+
+  test('day after Leap Day is Sol 1 — 2024', () => {
+    expect(toIFC('2024-06-18')).toMatchObject({
+      year: 2024, month: 7, day: 1, isLeapDay: false, isYearDay: false
+    });
+  });
+
+  test('Year Day non-leap — 2026', () => {
+    expect(toIFC('2026-12-31')).toMatchObject({
+      year: 2026, month: 13, day: 29, isLeapDay: false, isYearDay: true, weekday: null
+    });
+  });
+
+  test('Year Day leap — 2024', () => {
+    expect(toIFC('2024-12-31')).toMatchObject({
+      year: 2024, month: 13, day: 29, isLeapDay: false, isYearDay: true, weekday: null
+    });
+  });
+
+  test('Dec 28 non-leap — last normal day before Year Day', () => {
+    expect(toIFC('2026-12-30')).toMatchObject({
+      year: 2026, month: 13, day: 28, isLeapDay: false, isYearDay: false, weekday: 6
+    });
+  });
+
+  test('Jan 1 — first day of IFC year', () => {
+    expect(toIFC('2026-01-01')).toMatchObject({
+      year: 2026, month: 1, day: 1, isLeapDay: false, isYearDay: false, weekday: 0
+    });
+  });
+
+  test('Gregorian Feb 29 (leap) maps to IFC Mar 4', () => {
+    expect(toIFC('2024-02-29')).toMatchObject({
+      year: 2024, month: 3, day: 4, isLeapDay: false, isYearDay: false
+    });
+  });
+
+  test('Sol 1 non-leap is not affected by leap offset', () => {
+    expect(toIFC('2026-06-18')).toMatchObject({
+      year: 2026, month: 7, day: 1
+    });
+  });
+
+  test('throws on invalid date', () => {
+    expect(() => toIFC('not-a-date')).toThrow('Invalid date: not-a-date');
+  });
+
+  test('weekday is always 0 (Sun) for day 1 of any month', () => {
+    const result = toIFC('2026-01-01');
+    expect(result.weekday).toBe(0);
+  });
+
+  test('weekday is always 6 (Sat) for day 28 of any month', () => {
+    const result = toIFC('2026-01-28');
+    expect(result.weekday).toBe(6);
+  });
+
+  test('weekday is consistent across months — Sol 1 is always Sunday', () => {
+    expect(toIFC('2026-06-18').weekday).toBe(0);
+    expect(toIFC('2024-06-18').weekday).toBe(0);
+  });
+});
+
+// ─── toGregorian ──────────────────────────────────────────────────────────────
+describe('toGregorian', () => {
+  test('normal date — IFC Mar 22', () => {
+    expect(toGregorian('IFC:2026-03-22')).toBe('2026-03-19');
+  });
+
+  test('Sol 1 2026', () => {
+    expect(toGregorian('IFC:2026-07-01')).toBe('2026-06-18');
+  });
+
+  test('Leap Day 2024', () => {
+    expect(toGregorian('IFC:2024-06-29')).toBe('2024-06-17');
+  });
+
+  test('Year Day 2026', () => {
+    expect(toGregorian('IFC:2026-13-29')).toBe('2026-12-31');
+  });
+
+  test('Jan 1 — first day of IFC year', () => {
+    expect(toGregorian('IFC:2026-01-01')).toBe('2026-01-01');
+  });
+
+  test('Dec 28 — last normal IFC day before Year Day', () => {
+    expect(toGregorian('IFC:2026-13-28')).toBe('2026-12-30');
+  });
+
+  test('throws without IFC: prefix', () => {
+    expect(() => toGregorian('2024-06-17')).toThrow('IFC dates must be prefixed with "IFC:" e.g. IFC:2024-07-15');
+  });
+
+  test('throws on invalid month', () => {
+    expect(() => toGregorian('IFC:2024-14-01')).toThrow('IFC month must be 1-13, got 14');
+  });
+
+  test('throws on day 30', () => {
+    expect(() => toGregorian('IFC:2026-03-30')).toThrow('IFC day must be 1-29, got 30');
+  });
+
+  test('throws on day 29 in non-leap year June', () => {
+    expect(() => toGregorian('IFC:2026-06-29')).toThrow('Leap Day only exists in leap years');
+  });
+
+  test('throws on day 29 for non-special month', () => {
+    expect(() => toGregorian('IFC:2024-03-29')).toThrow('Day 29 only valid for June (leap years) or December');
+  });
+
+  test('round trip — Gregorian → IFC → Gregorian', () => {
+    const start = '2024-08-15';
+    const ifc   = toIFC(start);
+    const back  = toGregorian(`IFC:${ifc.year}-${ifc.month}-${ifc.day}`);
+    expect(back).toBe(start);
+  });
+
+  test('round trip — post leap day 2024', () => {
+    const start = '2024-09-01';
+    const ifc   = toIFC(start);
+    const back  = toGregorian(`IFC:${ifc.year}-${ifc.month}-${ifc.day}`);
+    expect(back).toBe(start);
+  });
+
+  test('round trip — Jan 1', () => {
+    const start = '2026-01-01';
+    const ifc   = toIFC(start);
+    const back  = toGregorian(`IFC:${ifc.year}-${ifc.month}-${ifc.day}`);
+    expect(back).toBe(start);
+  });
+});