islamic-date-adjustment 3.0.0 → 3.0.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "islamic-date-adjustment",
-  "version": "3.0.0",
+  "version": "3.0.1",
   "description": "Islamic (Hijri) calendar date adjustment library with Firebase persistence and React Native hook. Handles moon-sighting offsets, per-event adjustments, and month boundary edge cases.",
   "main": "src/index.js",
   "module": "src/index.js",
@@ -50,9 +50,9 @@
   "author": "",
   "license": "ISC",
   "peerDependencies": {
+    "@react-native-firebase/firestore": ">=14.0.0",
     "react": ">=16.8.0",
-    "react-native": ">=0.60.0",
-    "@react-native-firebase/firestore": ">=14.0.0"
+    "react-native": ">=0.60.0"
   },
   "peerDependenciesMeta": {
     "react": {
@@ -70,6 +70,9 @@
     "jest": "^30.2.0"
   },
   "dependencies": {
+    "moment": "^2.30.1",
+    "moment-hijri": "^3.0.0",
     "readline-sync": "^1.4.10"
-  }
+  },
+  "packageManager": "yarn@1.22.22+sha512.a6b2f7906b721bba3d67d4aff083df04dad64c399707841b7acf00f6b133b7ac24255f2652fa22ae3534329dc6180534e98d17432037ff6fd140556e2bb3137e"
 }

package/src/adjustmentEngine.js

@@ -258,6 +258,84 @@ export class HijriYear {
     return this;
   }
 
+  /**
+   * Get a list of selectable global-offset options the user can pick from.
+   *
+   * Each option shows:
+   *  - the offset value
+   *  - a human-readable label  (e.g. "+1 day", "-2 days", "(current)")
+   *  - the Muharram 1 (or first month) Gregorian date that would result
+   *  - a preview of how every month's start date shifts
+   *  - whether the option is valid (won't conflict with existing event adjustments)
+   *
+   * Use this to render a picker / radio-group so the user can visually
+   * compare options and then call `setGlobalOffset(chosen)`.
+   *
+   * @param {number} [range=3] – generate options from -range to +range
+   * @returns {GlobalOffsetOption[]}
+   */
+  getValidGlobalOffsets(range = 3) {
+    if (!Number.isInteger(range) || range < 0)
+      throw new Error("range must be a non-negative integer");
+
+    const currentGlobalOffset = this.globalOffset;
+    const currentAdjustments = [...this.adjustments];
+
+    const options = [];
+    for (let d = -range; d <= range; d++) {
+      const offset = d === 0 ? 0 : d; // avoid -0
+      const firstMonth = this._months[0];
+      const muharramDate = firstMonth.standardStart
+        ? addDays(firstMonth.standardStart, offset)
+        : null;
+
+      // Build a preview of all 12 month starts at this offset
+      const monthPreviews = this._months.map((m) => ({
+        index: m.index,
+        name: m.name,
+        adjustedStart: m.standardStart
+          ? formatDate(addDays(m.standardStart, offset))
+          : null,
+      }));
+
+      // Validate: try applying this offset and see if it causes errors
+      let valid = true;
+      let invalidReason = null;
+
+      if (offset !== currentGlobalOffset) {
+        try {
+          // Temporarily apply the offset
+          this.globalOffset = offset;
+          this._recalculate();
+        } catch (err) {
+          valid = false;
+          invalidReason = err.message;
+        } finally {
+          // Restore original state
+          this.globalOffset = currentGlobalOffset;
+          this.adjustments = currentAdjustments;
+          this._recalculate();
+        }
+      }
+
+      options.push({
+        offset,
+        label:
+          offset === 0
+            ? "(current)"
+            : offset > 0
+              ? `(+${offset} day${offset > 1 ? "s" : ""})`
+              : `(${offset} day${offset < -1 ? "s" : ""})`,
+        isCurrent: offset === currentGlobalOffset,
+        muharramStart: muharramDate ? formatDate(muharramDate) : null,
+        monthPreviews,
+        valid,
+        invalidReason,
+      });
+    }
+    return options;
+  }
+
   /**
    * Apply an event-based adjustment.
    *
@@ -568,6 +646,200 @@ export class HijriYear {
     return impact;
   }
 
+  // ══════════════════════════════════════════════
+  // MONTH-START ADJUSTMENTS
+  // ══════════════════════════════════════════════
+
+  /**
+   * Adjust a month's start date to a specific Gregorian date.
+   *
+   * This works for ANY month (1-12), unlike `adjustEvent` which requires
+   * a special event.  Internally it creates a synthetic day-1 adjustment
+   * so the existing recalculation logic handles everything correctly.
+   *
+   * @param {number} monthIndex – Hijri month index (1-12)
+   * @param {string} gregorianDate – "YYYY-MM-DD" target start date
+   * @returns {{ adjustment, message }}
+   */
+  adjustMonthStart(monthIndex, gregorianDate) {
+    const month = this._months.find((m) => m.index === monthIndex);
+    if (!month) throw new Error(`Unknown month index: ${monthIndex}`);
+    if (!month.adjustedStart)
+      throw new Error(`Month ${monthIndex} has no computed start date`);
+
+    const targetDate = parseDate(gregorianDate);
+    const currentStart = month.adjustedStart;
+    const offsetDelta = diffDays(targetDate, currentStart);
+
+    if (offsetDelta === 0) {
+      return {
+        adjustment: null,
+        message: `${month.name} already starts on ${formatDate(currentStart)}. No adjustment needed.`,
+      };
+    }
+
+    // Synthetic event id so it integrates with the adjustment pipeline
+    const syntheticEventId = `__month_${monthIndex}_start`;
+
+    const adj = {
+      eventId: syntheticEventId,
+      eventHijriMonth: monthIndex,
+      eventHijriDay: 1,
+      targetDate,
+      offsetDelta,
+    };
+
+    // Save state for rollback on validation failure
+    const prevAdjustments = [...this.adjustments];
+
+    // Remove any previous adjustment for this month start
+    this.adjustments = this.adjustments.filter(
+      (a) => a.eventId !== syntheticEventId,
+    );
+    this.adjustments.push(adj);
+
+    try {
+      this._recalculate();
+    } catch (err) {
+      this.adjustments = prevAdjustments;
+      this._recalculate();
+      throw err;
+    }
+
+    const direction = offsetDelta > 0 ? "later" : "earlier";
+    const absDelta = Math.abs(offsetDelta);
+    const lines = [
+      `✅ ${month.name} start adjusted: ${formatDate(currentStart)} → ${gregorianDate} (${absDelta} day${absDelta !== 1 ? "s" : ""} ${direction})`,
+    ];
+
+    const monthIdx = this._months.indexOf(month);
+    if (monthIdx > 0) {
+      const prev = this._months[monthIdx - 1];
+      lines.push(
+        `   📅 ${prev.name} is now ${prev.adjustedDays} days to accommodate the shift.`,
+      );
+    }
+    lines.push(`   📆 All months after ${month.name} are shifted accordingly.`);
+
+    return { adjustment: adj, message: lines.join("\n") };
+  }
+
+  /**
+   * Get valid date options for a month's start date.
+   * Returns only dates that keep the preceding month within 29-30 days.
+   *
+   * @param {number} monthIndex – Hijri month index (1-12)
+   * @param {number} [range=3] – check ± this many days from current start
+   * @returns {ValidOffset[]}
+   */
+  getValidMonthStartDates(monthIndex, range = 3) {
+    const month = this._months.find((m) => m.index === monthIndex);
+    if (!month || !month.adjustedStart) return [];
+
+    const monthIdx = this._months.indexOf(month);
+    const prevMonth = monthIdx > 0 ? this._months[monthIdx - 1] : null;
+
+    const offsets = [];
+    for (let d = -range; d <= range; d++) {
+      const date = addDays(month.adjustedStart, d);
+      let valid = true;
+
+      if (prevMonth && d !== 0) {
+        const newDays = prevMonth.adjustedDays + d;
+        if (newDays < MIN_MONTH_DAYS || newDays > MAX_MONTH_DAYS) {
+          valid = false;
+        }
+      }
+
+      offsets.push({
+        offset: d,
+        date: formatDate(date),
+        valid,
+        label:
+          d === 0
+            ? "(current)"
+            : d > 0
+              ? `(+${d} day${d > 1 ? "s" : ""})`
+              : `(${d} day${d < -1 ? "s" : ""})`,
+      });
+    }
+    return offsets;
+  }
+
+  /**
+   * Preview the impact of adjusting a month's start date WITHOUT changing state.
+   *
+   * @param {number} monthIndex – Hijri month index (1-12)
+   * @param {string} gregorianDate – "YYYY-MM-DD" proposed start date
+   * @returns {MonthStartImpact}
+   */
+  simulateMonthStartAdjustment(monthIndex, gregorianDate) {
+    const month = this._months.find((m) => m.index === monthIndex);
+    if (!month) throw new Error(`Unknown month index: ${monthIndex}`);
+    if (!month.adjustedStart)
+      throw new Error(`Month ${monthIndex} has no computed start date`);
+
+    const targetDate = parseDate(gregorianDate);
+    const currentStart = month.adjustedStart;
+    const offsetDelta = diffDays(targetDate, currentStart);
+
+    const impact = {
+      month: month.name,
+      monthIndex,
+      currentStart: formatDate(currentStart),
+      proposedStart: gregorianDate,
+      offsetDelta,
+      affectedMonths: [],
+      preservedMonths: [],
+      monthLengthChanges: [],
+    };
+
+    if (offsetDelta === 0) {
+      impact.noChange = true;
+      impact.valid = true;
+      return impact;
+    }
+
+    const monthIdx = this._months.indexOf(month);
+
+    // Months before the adjusted month are preserved
+    for (let i = 0; i < monthIdx; i++) {
+      impact.preservedMonths.push(this._months[i].name);
+    }
+
+    // Previous month absorbs the length change
+    if (monthIdx > 0) {
+      const prevMonth = this._months[monthIdx - 1];
+      const newDays = prevMonth.adjustedDays + offsetDelta;
+      // Remove prevMonth from preserved list (it gets modified)
+      impact.preservedMonths = impact.preservedMonths.filter(
+        (n) => n !== prevMonth.name,
+      );
+
+      const isValid = newDays >= MIN_MONTH_DAYS && newDays <= MAX_MONTH_DAYS;
+      impact.monthLengthChanges.push({
+        month: prevMonth.name,
+        originalDays: prevMonth.adjustedDays,
+        newDays,
+        valid: isValid,
+        reason: isValid
+          ? `${month.name} start moved by ${offsetDelta} day(s)`
+          : `${month.name} start moved by ${offsetDelta} day(s) — INVALID: ${newDays} days is outside ${MIN_MONTH_DAYS}–${MAX_MONTH_DAYS} range`,
+      });
+      impact.valid = isValid;
+    } else {
+      // Month 1 has no previous month — always valid
+      impact.valid = true;
+    }
+
+    // Months after are shifted
+    for (let i = monthIdx + 1; i < this._months.length; i++) {
+      impact.affectedMonths.push(this._months[i].name);
+    }
+
+    return impact;
+  }
+
   // ──── internal helpers ────
 
   _buildAdjustmentSummary(event, oldDate, newDate, delta) {

package/src/cli.js

@@ -98,23 +98,7 @@ function main() {
   const hijriYear = new HijriYear(hijriYearNum, monthStarts);
 
   // ── Step 3: Global offset ──
-  console.log("\n📌 Global Offset");
-  console.log(
-    "If your local moon sighting differs from the standard calendar,",
-  );
-  console.log(
-    "enter an offset (e.g. -2 means everything starts 2 days earlier).\n",
-  );
-
-  const offsetInput = readlineSync.question("Global offset in days [0]: ");
-  const globalOffset = offsetInput ? parseInt(offsetInput, 10) : 0;
-
-  if (globalOffset !== 0) {
-    hijriYear.setGlobalOffset(globalOffset);
-    console.log(
-      `\n✅ Global offset set to ${globalOffset}. All dates shifted.`,
-    );
-  }
+  promptGlobalOffset(hijriYear);
 
   // Show current calendar
   printCalendar(hijriYear);
@@ -126,11 +110,13 @@ function main() {
     console.log("\nWhat would you like to do?");
     console.log("  1. Check upcoming events");
     console.log("  2. Adjust a specific event");
-    console.log("  3. View full calendar");
-    console.log("  4. Check Hijri date for a Gregorian date");
-    console.log("  5. Exit\n");
+    console.log("  3. Change global offset");
+    console.log("  4. Adjust a month start date");
+    console.log("  5. View full calendar");
+    console.log("  6. Check Hijri date for a Gregorian date");
+    console.log("  7. Exit\n");
 
-    const choice = readlineSync.question("Choice [1-5]: ");
+    const choice = readlineSync.question("Choice [1-7]: ");
 
     switch (choice) {
       case "1":
@@ -140,16 +126,23 @@ function main() {
         handleEventAdjustment(hijriYear);
         break;
       case "3":
+        promptGlobalOffset(hijriYear);
         printCalendar(hijriYear);
         break;
       case "4":
-        handleDateLookup(hijriYear);
+        handleMonthStartAdjustment(hijriYear);
         break;
       case "5":
+        printCalendar(hijriYear);
+        break;
+      case "6":
+        handleDateLookup(hijriYear);
+        break;
+      case "7":
         continueAdjusting = false;
         break;
       default:
-        console.log("Invalid choice. Please enter 1-5.");
+        console.log("Invalid choice. Please enter 1-7.");
     }
   }
 
@@ -180,6 +173,170 @@ function promptMonthStarts() {
   return starts;
 }
 
+function promptGlobalOffset(hijriYear) {
+  console.log("\n📌 Global Offset");
+  console.log(
+    "If your local moon sighting differs from the standard calendar,",
+  );
+  console.log(
+    "pick an offset below. Each option shows how Muharram 1 shifts.\n",
+  );
+
+  const allOptions = hijriYear.getValidGlobalOffsets(3);
+  const options = allOptions.filter((opt) => opt.valid);
+
+  // Show warning if some options were filtered out
+  const invalidCount = allOptions.length - options.length;
+  if (invalidCount > 0) {
+    console.log(
+      `ℹ️  Note: ${invalidCount} offset option(s) hidden due to conflicts with existing event adjustments.\n`,
+    );
+  }
+
+  if (options.length === 0) {
+    console.log(
+      "⚠️  No valid global offset options available due to existing event adjustments.",
+    );
+    console.log(
+      "   Consider removing event adjustments first if you need to change the global offset.\n",
+    );
+    return;
+  }
+
+  console.log("  #   Offset   Muharram 1 starts   Ramadan starts");
+  printDivider();
+  options.forEach((opt, i) => {
+    const muharram = opt.muharramStart || "?";
+    const ramadan =
+      opt.monthPreviews.find((m) => m.index === 9)?.adjustedStart || "?";
+    const marker = opt.isCurrent ? " ◄ current" : "";
+    const mDate = opt.muharramStart ? parseDate(opt.muharramStart) : null;
+    const dayName = mDate ? ` (${weekday(mDate)})` : "";
+    console.log(
+      `  ${String(i + 1).padStart(2)}.  ${String(opt.offset >= 0 ? "+" + opt.offset : opt.offset).padStart(3)} days   ${muharram}${dayName.padEnd(8)}   ${ramadan}  ${opt.label}${marker}`,
+    );
+  });
+  printDivider();
+
+  const offsetChoice = readlineSync.question(
+    "\nSelect option number, or press Enter to keep current: ",
+  );
+
+  if (offsetChoice.trim() === "") {
+    console.log(`Global offset unchanged (${hijriYear.globalOffset}).`);
+    return;
+  }
+
+  const idx = parseInt(offsetChoice, 10) - 1;
+  if (idx >= 0 && idx < options.length) {
+    const chosen = options[idx].offset;
+    if (chosen !== hijriYear.globalOffset) {
+      hijriYear.setGlobalOffset(chosen);
+      console.log(
+        `\n✅ Global offset set to ${chosen >= 0 ? "+" : ""}${chosen}. All dates shifted.`,
+      );
+    } else {
+      console.log("No change — that's already the current offset.");
+    }
+  } else {
+    console.log("Invalid selection. Offset unchanged.");
+  }
+}
+
+function handleMonthStartAdjustment(hijriYear) {
+  console.log("\nAdjust a month's start date:");
+  const cal = hijriYear.getCalendar();
+  cal.forEach((m) => {
+    console.log(
+      `  ${String(m.index).padStart(2)}. ${m.name.padEnd(20)} starts: ${m.adjustedStart || "?"}`,
+    );
+  });
+
+  const monthChoice = readlineSync.question("\nSelect month number (1-12): ");
+  const monthIdx = parseInt(monthChoice, 10);
+  if (monthIdx < 1 || monthIdx > 12) {
+    console.log("Invalid selection.");
+    return;
+  }
+
+  const month = cal.find((m) => m.index === monthIdx);
+  console.log(`\n📅 ${month.name} currently starts on: ${month.adjustedStart}`);
+
+  // Show valid date options
+  const allDates = hijriYear.getValidMonthStartDates(monthIdx, 3);
+  const validDates = allDates.filter((o) => o.valid);
+  console.log("\nValid start date options:");
+  validDates.forEach((o, i) => {
+    const d = parseDate(o.date);
+    const marker = o.offset === 0 ? " ◄ current" : "";
+    console.log(
+      `  ${i + 1}. ${o.date} (${weekday(d)}) ${o.label}${marker}`,
+    );
+  });
+
+  const dateChoice = readlineSync.question(
+    "\nSelect option number, or enter a date (YYYY-MM-DD): ",
+  );
+
+  let targetDate;
+  const choiceNum = parseInt(dateChoice, 10);
+  if (!isNaN(choiceNum) && choiceNum >= 1 && choiceNum <= validDates.length) {
+    targetDate = validDates[choiceNum - 1].date;
+  } else {
+    targetDate = dateChoice.trim();
+  }
+
+  // Simulate first
+  try {
+    const impact = hijriYear.simulateMonthStartAdjustment(monthIdx, targetDate);
+    console.log("\n📊 Impact Analysis:");
+    printDivider();
+
+    if (impact.noChange) {
+      console.log("No change needed — the month already starts on this date.");
+      return;
+    }
+
+    console.log(`  Month: ${impact.month}`);
+    console.log(`  Current start: ${impact.currentStart}`);
+    console.log(`  Proposed start: ${impact.proposedStart}`);
+    console.log(
+      `  Offset: ${impact.offsetDelta > 0 ? "+" : ""}${impact.offsetDelta} day(s)`,
+    );
+
+    if (impact.preservedMonths.length > 0) {
+      console.log(
+        `  ✅ Preserved (unchanged): ${impact.preservedMonths.join(", ")}`,
+      );
+    }
+    if (impact.monthLengthChanges.length > 0) {
+      for (const ch of impact.monthLengthChanges) {
+        console.log(
+          `  📏 ${ch.month}: ${ch.originalDays} → ${ch.newDays} days (${ch.reason})`,
+        );
+      }
+    }
+    if (impact.affectedMonths.length > 0) {
+      console.log(
+        `  🔄 Shifted forward: ${impact.affectedMonths.join(", ")}`,
+      );
+    }
+
+    printDivider();
+
+    const confirm = readlineSync.keyInYNStrict("\nApply this adjustment? ");
+    if (confirm) {
+      const result = hijriYear.adjustMonthStart(monthIdx, targetDate);
+      console.log("\n" + result.message);
+      printCalendar(hijriYear);
+    } else {
+      console.log("Adjustment cancelled.");
+    }
+  } catch (err) {
+    console.log(`\n❌ Error: ${err.message}`);
+  }
+}
+
 function handleUpcomingEvents(hijriYear) {
   const refInput = readlineSync.question(
     "\nReference date (YYYY-MM-DD) [today]: ",

package/src/defaults.js

@@ -1,3 +1,4 @@
+import momentHijri from "moment-hijri";
 /**
  * defaults.js
  *
@@ -5,17 +6,19 @@
  * These can be used directly or overridden by the user.
  */
 
+const startOfHijriYear = momentHijri().locale("en").startOf("iYear");
+
 export const DEFAULT_1447_STARTS = {
-  1: "2025-06-26", // Muharram
-  2: "2025-07-26", // Safar
-  3: "2025-08-24", // Rabi al-Awwal
-  4: "2025-09-23", // Rabi al-Thani
-  5: "2025-10-22", // Jumada al-Ula
-  6: "2025-11-21", // Jumada al-Thani
-  7: "2025-12-20", // Rajab
-  8: "2026-01-19", // Shaban
-  9: "2026-02-17", // Ramadan
-  10: "2026-03-19", // Shawwal (Eid al-Fitr = 1 Shawwal)
-  11: "2026-04-17", // Dhul Qadah
-  12: "2026-05-17", // Dhul Hijjah
+  1: startOfHijriYear.format("YYYY-MM-DD"),
+  2: startOfHijriYear.clone().add(1, "iMonth").format("YYYY-MM-DD"),
+  3: startOfHijriYear.clone().add(2, "iMonth").format("YYYY-MM-DD"),
+  4: startOfHijriYear.clone().add(3, "iMonth").format("YYYY-MM-DD"),
+  5: startOfHijriYear.clone().add(4, "iMonth").format("YYYY-MM-DD"),
+  6: startOfHijriYear.clone().add(5, "iMonth").format("YYYY-MM-DD"),
+  7: startOfHijriYear.clone().add(6, "iMonth").format("YYYY-MM-DD"),
+  8: startOfHijriYear.clone().add(7, "iMonth").format("YYYY-MM-DD"),
+  9: startOfHijriYear.clone().add(8, "iMonth").format("YYYY-MM-DD"),
+  10: startOfHijriYear.clone().add(9, "iMonth").format("YYYY-MM-DD"),
+  11: startOfHijriYear.clone().add(10, "iMonth").format("YYYY-MM-DD"),
+  12: startOfHijriYear.clone().add(11, "iMonth").format("YYYY-MM-DD"),
 };

package/src/index.d.ts

@@ -100,6 +100,33 @@ export interface SimulationImpact {
   noChange?: boolean;
 }
 
+export interface MonthStartImpact {
+  month: string;
+  monthIndex: number;
+  currentStart: string;
+  proposedStart: string;
+  offsetDelta: number;
+  affectedMonths: string[];
+  preservedMonths: string[];
+  monthLengthChanges: MonthLengthChange[];
+  valid?: boolean;
+  noChange?: boolean;
+}
+
+export interface GlobalOffsetMonthPreview {
+  index: number;
+  name: string;
+  adjustedStart: string | null;
+}
+
+export interface GlobalOffsetOption {
+  offset: number;
+  label: string;
+  isCurrent: boolean;
+  muharramStart: string | null;
+  monthPreviews: GlobalOffsetMonthPreview[];
+}
+
 export declare class HijriYear {
   year: number;
   globalOffset: number;
@@ -108,6 +135,7 @@ export declare class HijriYear {
   constructor(year: number, monthStarts: Record<number, string>);
 
   setGlobalOffset(offset: number): this;
+  getValidGlobalOffsets(range?: number): GlobalOffsetOption[];
   adjustEvent(eventId: string, actualGregorianDate: string): AdjustEventResult;
   getValidOffsets(eventId: string, range?: number): ValidOffset[];
   getEventDate(eventId: string): Date | null;
@@ -125,6 +153,15 @@ export declare class HijriYear {
     eventId: string,
     actualGregorianDate: string,
   ): SimulationImpact;
+  adjustMonthStart(
+    monthIndex: number,
+    gregorianDate: string,
+  ): AdjustEventResult;
+  getValidMonthStartDates(monthIndex: number, range?: number): ValidOffset[];
+  simulateMonthStartAdjustment(
+    monthIndex: number,
+    gregorianDate: string,
+  ): MonthStartImpact;
 }
 
 // ──────────────────────────────────────────────
@@ -197,8 +234,17 @@ export interface UseHijriYearReturn {
   adjustEvent(eventId: string, date: string): AdjustEventResult;
   simulateAdjustment(eventId: string, date: string): SimulationImpact;
   getValidOffsets(eventId: string, range?: number): ValidOffset[];
+  getValidGlobalOffsets(range?: number): GlobalOffsetOption[];
   reset(): void;
 
+  // Month-start adjustments
+  adjustMonthStart(monthIndex: number, date: string): AdjustEventResult;
+  getValidMonthStartDates(monthIndex: number, range?: number): ValidOffset[];
+  simulateMonthStartAdjustment(
+    monthIndex: number,
+    date: string,
+  ): MonthStartImpact;
+
   // Queries
   getEventDate(eventId: string): string | null;
   getMonthStart(monthIndex: number): string | null;

package/src/useHijriYear.js

@@ -159,11 +159,45 @@ export function useHijriYear({
     [instance],
   );
 
+  const getValidGlobalOffsets = useCallback(
+    (range = 3) => {
+      return instance.getValidGlobalOffsets(range);
+    },
+    [instance],
+  );
+
   const reset = useCallback(() => {
     const hy = buildInitial();
     updateInstance(hy);
   }, [buildInitial, updateInstance]);
 
+  // ── Month-start adjustments ──
+
+  const adjustMonthStart = useCallback(
+    (monthIndex, date) => {
+      const result = instance.adjustMonthStart(monthIndex, date);
+      updateInstance(instance);
+      return result;
+    },
+    [instance, updateInstance],
+  );
+
+  const getValidMonthStartDates = useCallback(
+    (monthIndex, range = 3) => {
+      return instance
+        .getValidMonthStartDates(monthIndex, range)
+        .filter((o) => o.valid);
+    },
+    [instance],
+  );
+
+  const simulateMonthStartAdjustment = useCallback(
+    (monthIndex, date) => {
+      return instance.simulateMonthStartAdjustment(monthIndex, date);
+    },
+    [instance],
+  );
+
   // ══════════════════════════════════════════════
   // Derived / computed data
   // ══════════════════════════════════════════════
@@ -233,8 +267,14 @@ export function useHijriYear({
     adjustEvent,
     simulateAdjustment,
     getValidOffsets,
+    getValidGlobalOffsets,
     reset,
 
+    // Month-start adjustments
+    adjustMonthStart,
+    getValidMonthStartDates,
+    simulateMonthStartAdjustment,
+
     // Queries
     getEventDate,
     getMonthStart,

package/tests/adjustmentEngine.test.js

@@ -160,6 +160,92 @@ describe("Global offset", () => {
   });
 });
 
+// ═══════════════════════════════════════════════
+// 2b. getValidGlobalOffsets – selectable offset options
+// ═══════════════════════════════════════════════
+
+describe("getValidGlobalOffsets", () => {
+  test("returns 2*range+1 options by default (range=3 → 7 options)", () => {
+    const hy = freshYear();
+    const options = hy.getValidGlobalOffsets();
+    expect(options).toHaveLength(7); // -3, -2, -1, 0, +1, +2, +3
+  });
+
+  test("respects custom range", () => {
+    const hy = freshYear();
+    expect(hy.getValidGlobalOffsets(1)).toHaveLength(3); // -1, 0, +1
+    expect(hy.getValidGlobalOffsets(5)).toHaveLength(11);
+  });
+
+  test("offset=0 is marked isCurrent when globalOffset is 0", () => {
+    const hy = freshYear();
+    const options = hy.getValidGlobalOffsets();
+    const current = options.find((o) => o.isCurrent);
+    expect(current).toBeDefined();
+    expect(current.offset).toBe(0);
+  });
+
+  test("after setGlobalOffset(-2), offset=-2 is marked isCurrent", () => {
+    const hy = freshYear();
+    hy.setGlobalOffset(-2);
+    const options = hy.getValidGlobalOffsets();
+    const current = options.find((o) => o.isCurrent);
+    expect(current).toBeDefined();
+    expect(current.offset).toBe(-2);
+  });
+
+  test("each option shows the correct Muharram start date", () => {
+    const hy = freshYear();
+    const options = hy.getValidGlobalOffsets(2);
+    // Standard Muharram = 2025-06-26
+    expect(options.find((o) => o.offset === 0).muharramStart).toBe("2025-06-26");
+    expect(options.find((o) => o.offset === -1).muharramStart).toBe("2025-06-25");
+    expect(options.find((o) => o.offset === 1).muharramStart).toBe("2025-06-27");
+    expect(options.find((o) => o.offset === -2).muharramStart).toBe("2025-06-24");
+    expect(options.find((o) => o.offset === 2).muharramStart).toBe("2025-06-28");
+  });
+
+  test("each option includes monthPreviews for all 12 months", () => {
+    const hy = freshYear();
+    const options = hy.getValidGlobalOffsets(1);
+    for (const opt of options) {
+      expect(opt.monthPreviews).toHaveLength(12);
+      expect(opt.monthPreviews[0].name).toBe("Muharram");
+      expect(opt.monthPreviews[8].name).toBe("Ramadan");
+    }
+  });
+
+  test("monthPreviews reflect the offset correctly", () => {
+    const hy = freshYear();
+    const options = hy.getValidGlobalOffsets(1);
+    // Standard Ramadan = 2026-02-17. At offset -1 → 2026-02-16
+    const minusOne = options.find((o) => o.offset === -1);
+    expect(minusOne.monthPreviews[8].adjustedStart).toBe("2026-02-16");
+  });
+
+  test("labels are human-readable", () => {
+    const hy = freshYear();
+    const options = hy.getValidGlobalOffsets(2);
+    expect(options.find((o) => o.offset === 0).label).toBe("(current)");
+    expect(options.find((o) => o.offset === 1).label).toBe("(+1 day)");
+    expect(options.find((o) => o.offset === 2).label).toBe("(+2 days)");
+    expect(options.find((o) => o.offset === -1).label).toBe("(-1 day)");
+    expect(options.find((o) => o.offset === -2).label).toBe("(-2 days)");
+  });
+
+  test("range=0 returns only one option", () => {
+    const hy = freshYear();
+    const options = hy.getValidGlobalOffsets(0);
+    expect(options).toHaveLength(1);
+    expect(options[0].offset).toBe(0);
+  });
+
+  test("throws on negative range", () => {
+    const hy = freshYear();
+    expect(() => hy.getValidGlobalOffsets(-1)).toThrow("non-negative");
+  });
+});
+
 // ═══════════════════════════════════════════════
 // 3. THE CRITICAL SCENARIO: USER'S EXACT EXAMPLE
 //    Ramadan starts at Feb 18 standard, user offset -2 → starts fasting Feb 16.
@@ -980,3 +1066,207 @@ describe("Month-length validation (29–30 days)", () => {
     );
   });
 });
+
+// ══════════════════════════════════════════════
+// adjustMonthStart / getValidMonthStartDates / simulateMonthStartAdjustment
+// ══════════════════════════════════════════════
+describe("adjustMonthStart", () => {
+  // Note: Shaban (month 8) has 29 standard days.
+  // Moving Ramadan later → Shaban 29→30 ✓
+  // Moving Ramadan earlier → Shaban 29→28 ✗
+
+  test("moves Ramadan start 1 day later (Shaban 29→30)", () => {
+    const hy = freshYear();
+    const originalStart = formatDate(hy.getMonthStart(9));
+    const target = formatDate(addDays(parseDate(originalStart), 1));
+
+    const result = hy.adjustMonthStart(9, target);
+    expect(result.adjustment).not.toBeNull();
+    expect(formatDate(hy.getMonthStart(9))).toBe(target);
+  });
+
+  test("moves Safar start 1 day earlier (Muharram 30→29)", () => {
+    const hy = freshYear();
+    const originalStart = formatDate(hy.getMonthStart(2));
+    const target = formatDate(addDays(parseDate(originalStart), -1));
+
+    const result = hy.adjustMonthStart(2, target);
+    expect(result.adjustment).not.toBeNull();
+    expect(formatDate(hy.getMonthStart(2))).toBe(target);
+  });
+
+  test("previous month absorbs the delta (Shaban grows by 1)", () => {
+    const hy = freshYear();
+    const shabanDaysBefore = hy.getMonthDays(8); // Shaban = 29
+    const originalStart = formatDate(hy.getMonthStart(9));
+    const target = formatDate(addDays(parseDate(originalStart), 1));
+
+    hy.adjustMonthStart(9, target);
+    expect(hy.getMonthDays(8)).toBe(shabanDaysBefore + 1); // 29 → 30
+  });
+
+  test("no change when target equals current start", () => {
+    const hy = freshYear();
+    const currentStart = formatDate(hy.getMonthStart(9));
+
+    const result = hy.adjustMonthStart(9, currentStart);
+    expect(result.adjustment).toBeNull();
+    expect(result.message).toMatch(/No adjustment needed/);
+  });
+
+  test("throws for invalid month index", () => {
+    const hy = freshYear();
+    expect(() => hy.adjustMonthStart(99, "2026-01-01")).toThrow(
+      /Unknown month/,
+    );
+  });
+
+  test("rolls back on validation failure (would exceed 30 days)", () => {
+    const hy = freshYear();
+    const originalStart = formatDate(hy.getMonthStart(9));
+    const shabanDaysBefore = hy.getMonthDays(8);
+
+    // Try to push Ramadan 2 days later → Shaban would be 31 days
+    const target = formatDate(addDays(parseDate(originalStart), 2));
+    expect(() => hy.adjustMonthStart(9, target)).toThrow(/29–30/);
+
+    // State should be rolled back
+    expect(formatDate(hy.getMonthStart(9))).toBe(originalStart);
+    expect(hy.getMonthDays(8)).toBe(shabanDaysBefore);
+  });
+
+  test("months after the adjusted month rechain forward", () => {
+    const hy = freshYear();
+    const originalShawwalStart = formatDate(hy.getMonthStart(10));
+    const ramadanStart = formatDate(hy.getMonthStart(9));
+    const target = formatDate(addDays(parseDate(ramadanStart), 1));
+
+    hy.adjustMonthStart(9, target);
+
+    // Shawwal should also shift 1 day later
+    const newShawwalStart = formatDate(hy.getMonthStart(10));
+    expect(newShawwalStart).toBe(
+      formatDate(addDays(parseDate(originalShawwalStart), 1)),
+    );
+  });
+
+  test("works for month 1 (Muharram — no previous month)", () => {
+    const hy = freshYear();
+    const originalStart = formatDate(hy.getMonthStart(1));
+    const target = formatDate(addDays(parseDate(originalStart), -1));
+
+    const result = hy.adjustMonthStart(1, target);
+    expect(result.adjustment).not.toBeNull();
+    expect(formatDate(hy.getMonthStart(1))).toBe(target);
+  });
+
+  test("works with global offset already applied", () => {
+    const hy = freshYear();
+    hy.setGlobalOffset(-1);
+    // After global offset -1, Shaban is still 29 days, so only +1 is valid
+    const ramadanStart = formatDate(hy.getMonthStart(9));
+    const target = formatDate(addDays(parseDate(ramadanStart), 1));
+
+    hy.adjustMonthStart(9, target);
+    expect(formatDate(hy.getMonthStart(9))).toBe(target);
+  });
+
+  test("works for months without special events (e.g. Safar, Muharram 30→29)", () => {
+    const hy = freshYear();
+    const originalStart = formatDate(hy.getMonthStart(2)); // Safar
+    // Muharram has 30 days, so Safar can move 1 day earlier (Muharram→29)
+    const target = formatDate(addDays(parseDate(originalStart), -1));
+
+    const result = hy.adjustMonthStart(2, target);
+    expect(result.adjustment).not.toBeNull();
+    expect(formatDate(hy.getMonthStart(2))).toBe(target);
+  });
+});
+
+describe("getValidMonthStartDates", () => {
+  test("returns array of valid date options for a month", () => {
+    const hy = freshYear();
+    const offsets = hy.getValidMonthStartDates(9);
+    expect(offsets.length).toBe(7); // -3 to +3
+    expect(offsets[3].offset).toBe(0);
+    expect(offsets[3].label).toBe("(current)");
+  });
+
+  test("marks invalid dates where previous month would exceed 29-30", () => {
+    const hy = freshYear();
+    const offsets = hy.getValidMonthStartDates(9);
+    const invalidOnes = offsets.filter((o) => !o.valid);
+    expect(invalidOnes.length).toBeGreaterThan(0);
+  });
+
+  test("all offsets have date, offset, valid, label properties", () => {
+    const hy = freshYear();
+    const offsets = hy.getValidMonthStartDates(5);
+    for (const o of offsets) {
+      expect(o).toHaveProperty("offset");
+      expect(o).toHaveProperty("date");
+      expect(o).toHaveProperty("valid");
+      expect(o).toHaveProperty("label");
+    }
+  });
+
+  test("returns empty for unknown month", () => {
+    const hy = freshYear();
+    expect(hy.getValidMonthStartDates(99)).toEqual([]);
+  });
+
+  test("custom range", () => {
+    const hy = freshYear();
+    const offsets = hy.getValidMonthStartDates(9, 1);
+    expect(offsets.length).toBe(3); // -1, 0, +1
+  });
+});
+
+describe("simulateMonthStartAdjustment", () => {
+  test("returns impact without changing state", () => {
+    const hy = freshYear();
+    const originalStart = formatDate(hy.getMonthStart(9));
+    const target = formatDate(addDays(parseDate(originalStart), 1));
+
+    const impact = hy.simulateMonthStartAdjustment(9, target);
+    expect(impact.month).toBe("Ramadan");
+    expect(impact.offsetDelta).toBe(1);
+    expect(impact.valid).toBe(true);
+
+    // State should NOT have changed
+    expect(formatDate(hy.getMonthStart(9))).toBe(originalStart);
+  });
+
+  test("noChange when target equals current start", () => {
+    const hy = freshYear();
+    const current = formatDate(hy.getMonthStart(9));
+    const impact = hy.simulateMonthStartAdjustment(9, current);
+    expect(impact.noChange).toBe(true);
+    expect(impact.valid).toBe(true);
+  });
+
+  test("marks invalid when previous month would exceed bounds", () => {
+    const hy = freshYear();
+    const target = formatDate(addDays(hy.getMonthStart(9), 2));
+    const impact = hy.simulateMonthStartAdjustment(9, target);
+    expect(impact.valid).toBe(false);
+    expect(impact.monthLengthChanges[0].valid).toBe(false);
+  });
+
+  test("lists preserved and affected months", () => {
+    const hy = freshYear();
+    const target = formatDate(addDays(hy.getMonthStart(9), 1));
+    const impact = hy.simulateMonthStartAdjustment(9, target);
+
+    expect(impact.preservedMonths.length).toBeGreaterThan(0);
+    expect(impact.affectedMonths).toContain("Shawwal");
+    expect(impact.affectedMonths).toContain("Dhul Hijjah");
+  });
+
+  test("throws for unknown month index", () => {
+    const hy = freshYear();
+    expect(() => hy.simulateMonthStartAdjustment(99, "2026-01-01")).toThrow(
+      /Unknown month/,
+    );
+  });
+});