@celestia-island/hikari 0.55.234 → 0.55.235

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celestia-island/hikari",
-  "version": "0.55.234",
+  "version": "0.55.235",
   "private": false,
   "type": "module",
   "description": "Hikari UI library, Vue 3 runtime — one design system for Vue 3 and Rust/WASM applications",

package/src/components/HkCalendarHeatmap.barrel.test.ts

@@ -0,0 +1,48 @@
+import { describe, expect, it } from "vitest";
+import * as barrel from "../index";
+
+/**
+ * The public barrel guard for the calendar heatmap's exports (R3 on the
+ * S3-fix wave: deleting any of these lines from index.ts kept the ENTIRE
+ * suite green, because every other test reaches the module through the
+ * direct "./calendarHeatmap" path — only an external consumer would have
+ * noticed). Same shape as HkFaceShell.barrel.test.ts.
+ *
+ * This file deliberately does NOT mock "@celestia-island/hikari": the
+ * package's self-reference resolves to the very same src/index.ts module
+ * as "../index", so a vi.mock here would replace the barrel under test
+ * with the mock's own namespace.
+ */
+describe("the public barrel", () => {
+  it("exports the heatmap component under both family names", () => {
+    const hk = barrel.HkCalendarHeatmap as unknown as { name?: string };
+    expect(hk, "HkCalendarHeatmap must be re-exported").toBeTruthy();
+    expect(hk.name).toBe("HkCalendarHeatmap");
+    // The H- alias rides the HCard/HkCard family convention.
+    expect(barrel.HCalendarHeatmap).toBe(barrel.HkCalendarHeatmap);
+  });
+
+  it("exports the calendar grid math and the fill ladder", () => {
+    for (const name of [
+      "bucketLevel",
+      "calendarGrid",
+      "heatmapCellFill",
+      "heatmapCellOpacity",
+      "monthMarkers",
+      "todayIso",
+      "weekdayIndex",
+      "shiftIso",
+    ] as const) {
+      expect(typeof barrel[name], `${name} must be re-exported`).toBe("function");
+    }
+    expect(Array.isArray(barrel.HEATMAP_LEVEL_OPACITY)).toBe(true);
+    expect(barrel.HEATMAP_LEVEL_OPACITY).toHaveLength(4);
+    expect(typeof barrel.HEATMAP_EMPTY_FILL).toBe("string");
+    // The fill ladder the legend and the cells share: level 0 is the
+    // empty wash, never the primary token.
+    expect(barrel.heatmapCellFill(0)).toBe(barrel.HEATMAP_EMPTY_FILL);
+    expect(barrel.heatmapCellFill(0)).not.toContain("primary");
+    expect(barrel.heatmapCellOpacity(0)).toBeUndefined();
+    expect(barrel.heatmapCellOpacity(4)).toBe(barrel.HEATMAP_LEVEL_OPACITY[3]);
+  });
+});

package/src/components/HkCalendarHeatmap.test.tsx

@@ -2,7 +2,7 @@ import { afterEach, describe, expect, it, vi } from "vitest";
 import { createApp, defineComponent, h, nextTick, reactive } from "vue";
 
 import HkCalendarHeatmap from "./HkCalendarHeatmap";
-import { HEATMAP_LEVEL_OPACITY, todayIso } from "./calendarHeatmap";
+import { HEATMAP_LEVEL_OPACITY, shiftIso } from "./calendarHeatmap";
 
 const mounts: Array<{ app: ReturnType<typeof createApp>; container: HTMLElement }> = [];
 
@@ -16,6 +16,9 @@ function mount(node: ReturnType<typeof h>) {
 }
 
 afterEach(() => {
+  // A failed assertion inside a fake-clock test must not leak the frozen
+  // clock into the rest of the file.
+  vi.useRealTimers();
   for (const { app, container } of mounts.splice(0)) {
     app.unmount();
     container.remove();
@@ -35,7 +38,7 @@ const daysFrom = (start: string, count: number, value = 0) =>
   });
 
 describe("HkCalendarHeatmap", () => {
-  it("renders the legend (less → more, five swatches) and the grid anatomy", () => {
+  it("renders the legend (less → more, the empty swatch + one per level) and the grid anatomy", () => {
     const c = mount(
       h(HkCalendarHeatmap, {
         days: daysFrom(CLEAN_HEAD_MON, 7),
@@ -51,18 +54,35 @@ describe("HkCalendarHeatmap", () => {
     const legend = c.querySelector('[data-testid="hk-calendar-heatmap-legend"]');
     expect(legend?.textContent).toContain("Less");
     expect(legend?.textContent).toContain("More");
+    // The empty swatch plus one per CONSUMING level.
     expect(c.querySelectorAll("[data-legend-level]")).toHaveLength(
-      HEATMAP_LEVEL_OPACITY.length,
+      1 + HEATMAP_LEVEL_OPACITY.length,
     );
+    const swatches = c.querySelectorAll("[data-legend-level]") as NodeListOf<HTMLElement>;
+    // The empty swatch carries NO opacity step (its wash lives in the
+    // fill, HEATMAP_EMPTY_FILL — happy-dom drops color-mix() values, so
+    // the ladder is asserted through the opacity channel it does keep).
+    expect(swatches[0].style.opacity).toBe("");
+    // The swatch levels run 0..4 in order, empty first.
+    expect(
+      Array.from(swatches, (s) => s.getAttribute("data-legend-level")),
+    ).toEqual(["0", "1", "2", "3", "4"]);
+    // Consuming levels index the table by level - 1: 1 -> [0] … 4 -> [3].
+    expect(swatches[1].style.opacity).toBe(HEATMAP_LEVEL_OPACITY[0]);
+    expect(swatches[2].style.opacity).toBe(HEATMAP_LEVEL_OPACITY[1]);
+    expect(swatches[3].style.opacity).toBe(HEATMAP_LEVEL_OPACITY[2]);
+    expect(swatches[4].style.opacity).toBe(HEATMAP_LEVEL_OPACITY[3]);
     // One week of days, all level 0 (no consumption): plain muted cells.
     expect(grid.querySelectorAll('[data-level="0"]')).toHaveLength(7);
   });
 
-  it("suppresses the leading month marker when the window starts mid-month", async () => {
+  it("labels the next month on the column carrying its 1st, never the partial head month", async () => {
     const c = mount(
       h(HkCalendarHeatmap, {
-        // Trailing-October tail + November: the partial October head is
-        // unlabeled, November's Monday carries the only marker.
+        // Trailing-October tail + November. October's 1st is not on the
+        // axis, so no slot may carry October; November's 1st (Nov 1, a
+        // Saturday) sits in the HEAD column, which is where its marker
+        // goes.
         days: daysFrom(MID_MONTH_MON, 10),
         first: null,
       }),
@@ -72,8 +92,63 @@ describe("HkCalendarHeatmap", () => {
       ".hk-calendar-heatmap-markers > span",
     ) as NodeListOf<HTMLElement>;
     expect(markers.length).toBeGreaterThanOrEqual(2);
-    expect(markers[0].textContent).toBe(""); // partial October — suppressed
-    expect(markers[1].textContent).not.toBe(""); // November — labeled
+    const texts = Array.from(markers, (m) => m.textContent);
+    // The head month (its 1st is off-axis) is never labeled.
+    expect(texts.some((t) => t?.startsWith("Oct"))).toBe(false);
+    expect(texts[0]).not.toBe(""); // November's 1st is in this column
+    expect(texts[1]).toBe("");
+  });
+
+  it("labels a month on the column carrying its 1st, not one column late", async () => {
+    // Grid opens Mon Sep 29: Oct 1 (a Wednesday) is in the head column.
+    const c = mount(
+      h(HkCalendarHeatmap, {
+        days: Array.from({ length: 14 }, (_, i) => ({
+          date: shiftIso("2025-09-29", i),
+          value: 0,
+        })),
+        first: null,
+      }),
+    );
+    await nextTick();
+    const markers = c.querySelectorAll(
+      ".hk-calendar-heatmap-markers > span",
+    ) as NodeListOf<HTMLElement>;
+    expect(markers[0].textContent).not.toBe(""); // October, mid-column
+    expect(markers[1].textContent).toBe("");
+  });
+
+  it("reserves trailing room exactly when the last column carries a marker", async () => {
+    const padOf = async (days: { date: string; value: number }[]) => {
+      const c = mount(h(HkCalendarHeatmap, { days, first: null }));
+      await nextTick();
+      const markersEl = c.querySelector(
+        ".hk-calendar-heatmap-markers",
+      ) as HTMLElement;
+      const texts = Array.from(
+        markersEl.querySelectorAll(":scope > span"),
+        (m) => m.textContent,
+      );
+      return {
+        // Logical property: hikari ships RTL hosts (HkMenu reads
+        // documentElement.dir), so the reserved room rides inline-end
+        // rather than a physical side.
+        pad: markersEl.style.paddingInlineEnd,
+        lastSet: texts.length > 0 && texts[texts.length - 1] !== "",
+      };
+    };
+
+    // Positive branch: a single week opening on Dec 1 leaves the marker
+    // on the LAST column — its ink needs the reserved room.
+    const marked = await padOf(daysFrom(CLEAN_HEAD_MON, 7));
+    expect(marked.lastSet).toBe(true);
+    expect(marked.pad).not.toBe("");
+
+    // Negative branch: ending on Nov 7 (a Friday) pads the axis to
+    // Nov 3–9, so the November marker sits one column in, not last.
+    const unmarked = await padOf(daysFrom("2025-10-27", 12));
+    expect(unmarked.lastSet).toBe(false);
+    expect(unmarked.pad).toBe("");
   });
 
   it("shows the leading month marker when the grid's first column opens its month", async () => {
@@ -90,29 +165,97 @@ describe("HkCalendarHeatmap", () => {
     expect(markers[0].textContent).not.toBe(""); // Dec 1 — labeled
   });
 
-  it("renders gap cells hatched and inert (no tooltip, no level claim)", () => {
-    // A one-day series AT today, anchored at first = today: the head
-    // padding hatches as "before", the tail as "after" — both phases in
-    // one grid, all deterministic against the real clock.
-    const today = todayIso();
+  it("fills the cells through the shared ladder: consuming levels primary, level 0 not", () => {
+    // happy-dom drops color-mix() but keeps var(), so the
+    // empty-vs-primary distinction IS observable here — a hardcoded
+    // primary for level 0 (or a hardcoded fill that ignores the
+    // helper) turns this red (R3: the call sites had no pin).
     const c = mount(
       h(HkCalendarHeatmap, {
-        days: [{ date: today, value: 5 }],
-        first: today,
+        days: [
+          { date: CLEAN_HEAD_MON, value: 10 },
+          { date: "2025-12-02", value: 0 },
+        ],
+        first: null,
       }),
     );
     const grid = c.querySelector('[data-testid="hk-calendar-heatmap"]') as HTMLElement;
-    const gaps = grid.querySelectorAll("[data-gap]") as NodeListOf<HTMLElement>;
-    expect(gaps.length).toBeGreaterThan(0);
-    const phases = new Set(
-      Array.from(gaps, (gap) => gap.getAttribute("data-gap")),
+    const styleOf = (level: string) =>
+      (grid.querySelector(`[data-level="${level}"]`) as HTMLElement).getAttribute(
+        "style",
+      ) ?? "";
+    expect(styleOf("4")).toContain("var(--hi-color-primary)");
+    expect(styleOf("0")).not.toContain("--hi-color-primary");
+    // The legend rides the same decision: its empty swatch is not
+    // primary, every consuming swatch is.
+    const swatches = c.querySelectorAll(
+      "[data-legend-level]",
+    ) as NodeListOf<HTMLElement>;
+    expect(swatches[0].getAttribute("style") ?? "").not.toContain(
+      "--hi-color-primary",
+    );
+    for (const level of [1, 2, 3, 4]) {
+      expect(swatches[level].getAttribute("style") ?? "").toContain(
+        "var(--hi-color-primary)",
+      );
+    }
+  });
+
+  it("applies the opacity ladder by level - 1, leaving level 0 without an opacity step", () => {
+    // The empty cell's wash lives in its FILL, never in the opacity
+    // table (the old table's index 0 was dead weight) — level 0 must
+    // carry no opacity while every consuming level maps to [level - 1].
+    const c = mount(
+      h(HkCalendarHeatmap, {
+        days: [
+          { date: CLEAN_HEAD_MON, value: 10 },
+          { date: "2025-12-02", value: 5 },
+          { date: "2025-12-03", value: 0 },
+        ],
+        first: null,
+      }),
     );
-    expect(phases.has("before")).toBe(true);
-    expect(phases.has("after")).toBe(true);
-    for (const gap of gaps) {
-      expect(gap.getAttribute("aria-hidden")).toBe("true");
-      expect(gap.getAttribute("title")).toBeNull();
-      expect(gap.style.pointerEvents).toBe("none");
+    const grid = c.querySelector('[data-testid="hk-calendar-heatmap"]') as HTMLElement;
+    const cellAt = (level: string) =>
+      grid.querySelector(`[data-level="${level}"]`) as HTMLElement;
+    expect(cellAt("4").style.opacity).toBe(HEATMAP_LEVEL_OPACITY[3]);
+    expect(cellAt("2").style.opacity).toBe(HEATMAP_LEVEL_OPACITY[1]);
+    expect(cellAt("0").style.opacity).toBe("");
+  });
+
+  it("renders gap cells hatched and inert (no tooltip, no level claim)", () => {
+    // A one-day series AT today, anchored at first = today: the head
+    // padding hatches as "before", the tail as "after". The clock is
+    // PINNED to a Wednesday: with the real clock this test carried
+    // both-phase expectations into a Monday (no head padding) or a
+    // Sunday (no tail), so it went red two days out of seven
+    // (R3 2026-10-30, proven with a mocked clock).
+    vi.useFakeTimers();
+    try {
+      vi.setSystemTime(new Date("2025-12-03T10:00:00Z")); // a Wednesday
+      const c = mount(
+        h(HkCalendarHeatmap, {
+          days: [{ date: "2025-12-03", value: 5 }],
+          first: "2025-12-03",
+        }),
+      );
+      const grid = c.querySelector(
+        '[data-testid="hk-calendar-heatmap"]',
+      ) as HTMLElement;
+      const gaps = grid.querySelectorAll("[data-gap]") as NodeListOf<HTMLElement>;
+      expect(gaps.length).toBeGreaterThan(0);
+      const phases = new Set(
+        Array.from(gaps, (gap) => gap.getAttribute("data-gap")),
+      );
+      expect(phases.has("before")).toBe(true);
+      expect(phases.has("after")).toBe(true);
+      for (const gap of gaps) {
+        expect(gap.getAttribute("aria-hidden")).toBe("true");
+        expect(gap.getAttribute("title")).toBeNull();
+        expect(gap.style.pointerEvents).toBe("none");
+      }
+    } finally {
+      vi.useRealTimers();
     }
   });
 

package/src/components/HkCalendarHeatmap.tsx

@@ -2,9 +2,9 @@ import { computed, defineComponent, type PropType } from "vue";
 
 import { useI18n } from "../i18n/context";
 import {
-  bucketLevel,
   calendarGrid,
-  HEATMAP_LEVEL_OPACITY,
+  heatmapCellFill,
+  heatmapCellOpacity,
   monthMarkers,
   todayIso,
   type CalendarCell,
@@ -12,6 +12,12 @@ import {
 } from "./calendarHeatmap";
 import "./HkCalendarHeatmap.scss";
 
+/** The legend's five levels, empty first — the same ladder the cells
+ * ride, so the swatches come from the one fill/opacity decision
+ * (`heatmapCellFill` / `heatmapCellOpacity`) rather than a second,
+ * hand-written copy of the colors. */
+const LEGEND_LEVELS = [0, 1, 2, 3, 4] as const;
+
 /** The no-data cell (before the account's first activity / after
  * today): muted diagonal hatch over the surface — the wowsp-style
  * "not yet" cell. Rendered inert: no tooltip, no pointer events. */
@@ -36,11 +42,10 @@ function fill(template: string, vars: Record<string, string | number>): string {
  * rail, month markers, and hatched no-data gap cells that never claim
  * a fake zero.
  *
- * The leading month is suppressed when the window starts mid-month:
- * the first column shows only the tail of its month, so the marker is
- * rendered only when the grid's first column actually opens its month
- * (Monday = the 1st) — a label over a partial head would claim a
- * month start that is not visible.
+ * The leading month is never mislabeled: a month is labeled on the
+ * column that carries its 1st, so a window starting mid-month has no
+ * label over its partial head (that month's 1st is not on the axis),
+ * and no month lands one column late.
  *
  * Dumb by design: the caller owns the fetch lifecycle and passes the
  * settled dense series in (`days`, oldest → newest, zero-filled,
@@ -90,33 +95,35 @@ export default defineComponent({
       () => `repeat(${weeks.value}, ${props.cellSize}px)`,
     );
 
-    // Locale-reactive (the HkDateTimePicker convention): a computed
-    // over the context's locale so a locale switch re-renders the
-    // calendar's Intl-formatted labels. All formatters format the UTC
-    // midnight instant WITH an explicit UTC zone (R2: on a negative-
-    // offset host the weekday rail shifted a full row and tooltips
-    // landed a day off — the series' day boundary is UTC).
+    // Locale-reactive formatter cache (the HkDateTimePicker convention):
+    // ONE Intl.DateTimeFormat per shape per locale, held in a computed
+    // over the context's locale — not one per rendered cell, which a
+    // full-year grid would pay ~370 times over. All formatters format
+    // the UTC midnight instant WITH an explicit UTC zone (R2: on a
+    // negative-offset host the weekday rail shifted a full row and
+    // tooltips landed a day off — the series' day boundary is UTC).
     const locale = computed(() => useI18n().locale);
+    const formatters = computed(() => {
+      const loc = locale.value;
+      return {
+        weekday: new Intl.DateTimeFormat(loc, { weekday: "short", timeZone: "UTC" }),
+        month: new Intl.DateTimeFormat(loc, { month: "short", timeZone: "UTC" }),
+        date: new Intl.DateTimeFormat(loc, { dateStyle: "medium", timeZone: "UTC" }),
+      };
+    });
     const weekdayLabel = (idx: number) =>
-      new Intl.DateTimeFormat(locale.value, {
-        weekday: "short",
-        timeZone: "UTC",
-      }).format(
+      formatters.value.weekday.format(
         // Any Monday-first week works — take 2024-01-01 (a Monday).
         new Date(Date.UTC(2024, 0, 1 + idx)),
       );
     const monthLabel = (m: string) => {
       if (!m) return "";
-      return new Intl.DateTimeFormat(locale.value, {
-        month: "short",
-        timeZone: "UTC",
-      }).format(new Date(Date.UTC(2024, Number(m) - 1, 1)));
+      return formatters.value.month.format(
+        new Date(Date.UTC(2024, Number(m) - 1, 1)),
+      );
     };
     const dateLabel = (iso: string) =>
-      new Intl.DateTimeFormat(locale.value, {
-        dateStyle: "medium",
-        timeZone: "UTC",
-      }).format(new Date(`${iso}T00:00:00Z`));
+      formatters.value.date.format(new Date(`${iso}T00:00:00Z`));
 
     const cellTitle = (d: Extract<CalendarCell, { kind: "day" }>) =>
       fill(
@@ -135,13 +142,24 @@ export default defineComponent({
           }
         : {
             borderRadius: "3px",
-            background:
-              cell.level === 0
-                ? "color-mix(in srgb, var(--hi-color-muted) 40%, transparent)"
-                : "var(--hi-color-primary)",
-            opacity: cell.level === 0 ? undefined : HEATMAP_LEVEL_OPACITY[cell.level],
+            background: heatmapCellFill(cell.level),
+            opacity: heatmapCellOpacity(cell.level),
           };
 
+    // A marker may overflow its 14px column into the empty columns
+    // ahead (the GitHub convention — a month label is always followed
+    // by unmarked columns). A marker on the LAST column has nothing
+    // ahead: its ink would be clipped by the scroll container, so that
+    // one case reserves inline-end room for it. The logical property
+    // matters: hikari ships RTL hosts (HkMenu reads
+    // documentElement.dir), and there the label runs the other way.
+    const markersTrailingPad = computed(() => {
+      const m = markers.value;
+      return m.length > 0 && m[m.length - 1] !== ""
+        ? `${props.cellSize * 2 + props.cellGap}px`
+        : undefined;
+    });
+
     return () => (
       <div class="hk-calendar-heatmap">
         {/* The legend row: the scale in the caller's one unit on the
@@ -154,19 +172,16 @@ export default defineComponent({
             data-testid="hk-calendar-heatmap-legend"
           >
             {t("hikari::calendarHeatmap.less", "Less")}
-            {HEATMAP_LEVEL_OPACITY.map((o, i) => (
+            {LEGEND_LEVELS.map((level) => (
               <span
-                key={i}
-                data-legend-level={i}
+                key={level}
+                data-legend-level={level}
                 style={{
                   width: "10px",
                   height: "10px",
                   borderRadius: "2px",
-                  background:
-                    i === 0
-                      ? "color-mix(in srgb, var(--hi-color-muted) 40%, transparent)"
-                      : "var(--hi-color-primary)",
-                  opacity: i === 0 ? undefined : o,
+                  background: heatmapCellFill(level),
+                  opacity: heatmapCellOpacity(level),
                   display: "inline-block",
                 }}
               />
@@ -199,14 +214,16 @@ export default defineComponent({
             </div>
 
             <div class="hk-calendar-heatmap-cells">
-              {/* Month markers, one slot per week column. A leading
-               * partial month renders its empty slot (see
+              {/* Month markers, one slot per week column. A month is
+               * labeled on the column carrying its 1st; a partial head
+               * month therefore renders an empty slot (see
                * monthMarkers). */}
               <div
                 class="hk-calendar-heatmap-markers"
                 style={{
                   gridTemplateColumns: columns.value,
                   columnGap: `${props.cellGap}px`,
+                  paddingInlineEnd: markersTrailingPad.value,
                 }}
               >
                 {markers.value.map((m, i) => (

package/src/components/calendarHeatmap.test.ts

@@ -3,6 +3,10 @@ import { describe, expect, it } from "vitest";
 import {
   bucketLevel,
   calendarGrid,
+  heatmapCellFill,
+  heatmapCellOpacity,
+  HEATMAP_EMPTY_FILL,
+  HEATMAP_LEVEL_OPACITY,
   monthMarkers,
   shiftIso,
   todayIso,
@@ -35,6 +39,28 @@ describe("todayIso", () => {
   });
 });
 
+describe("heatmapCellFill / heatmapCellOpacity — the empty cell is its own channel", () => {
+  it("fills level 0 with the empty wash and every consuming level with primary", () => {
+    expect(heatmapCellFill(0)).toBe(HEATMAP_EMPTY_FILL);
+    // The empty wash must never be the primary token in disguise.
+    expect(heatmapCellFill(0)).toContain("muted");
+    expect(heatmapCellFill(0)).not.toContain("primary");
+    for (const level of [1, 2, 3, 4] as const) {
+      expect(heatmapCellFill(level)).toBe("var(--hi-color-primary)");
+    }
+  });
+
+  it("leaves level 0 without an opacity step and maps 1..4 to the four consuming steps", () => {
+    expect(heatmapCellOpacity(0)).toBeUndefined();
+    expect(heatmapCellOpacity(1)).toBe(HEATMAP_LEVEL_OPACITY[0]);
+    expect(heatmapCellOpacity(2)).toBe(HEATMAP_LEVEL_OPACITY[1]);
+    expect(heatmapCellOpacity(3)).toBe(HEATMAP_LEVEL_OPACITY[2]);
+    expect(heatmapCellOpacity(4)).toBe(HEATMAP_LEVEL_OPACITY[3]);
+    // The ladder only ever holds the four consuming steps.
+    expect(HEATMAP_LEVEL_OPACITY).toHaveLength(4);
+  });
+});
+
 describe("bucketLevel", () => {
   it("keeps zero and negative days at level 0", () => {
     expect(bucketLevel(0, 10)).toBe(0);
@@ -124,10 +150,35 @@ describe("calendarGrid", () => {
   it("returns an empty grid for an empty series", () => {
     expect(calendarGrid([], "2025-12-03", null)).toEqual([]);
   });
+
+  it("never hatches a day the server shipped, even past a skewed `today`", () => {
+    // A skewed server clock (out of contract): the series runs one day
+    // past `today`. The shipped day must render as a real day — every
+    // day of the series vanishing behind the "after" hatch is the
+    // failure mode this guards.
+    const cells = calendarGrid(
+      [
+        { date: "2025-12-01", value: 5 },
+        { date: "2025-12-02", value: 3 },
+      ],
+      "2025-12-01",
+      null,
+    );
+    expect(cells.find((c) => c.date === "2025-12-02")).toMatchObject({
+      kind: "day",
+      value: 3,
+      level: 3,
+    });
+    // The unshipped padding past it still hatches.
+    expect(cells.find((c) => c.date === "2025-12-03")).toMatchObject({
+      kind: "gap",
+      phase: "after",
+    });
+  });
 });
 
-describe("monthMarkers — the leading-month suppression", () => {
-  it("shows the first marker only when the grid's first column opens its month", () => {
+describe("monthMarkers — a month is labeled on the column carrying its 1st", () => {
+  it("shows the first marker when the grid's first column opens its month", () => {
     // Grid starts exactly on Dec 1 (a Monday AND the 1st); one row of
     // days pads into exactly one week.
     const cells = calendarGrid(
@@ -140,9 +191,11 @@ describe("monthMarkers — the leading-month suppression", () => {
     expect(monthMarkers(cells)).toEqual(["12"]);
   });
 
-  it("suppresses a leading month that starts mid-month; the next month is labeled", () => {
+  it("never labels the partial head month — its 1st is not on the axis", () => {
     // Grid starts Oct 27 (a Monday, NOT the 1st) and runs into November;
-    // two full weeks of cells.
+    // two full weeks of cells. October's 1st is not in the grid, so no
+    // column may carry its label; November's 1st sits in the head
+    // column (Nov 1 is a Saturday there), so THAT column carries "11".
     const days: HkCalendarHeatmapDay[] = [
       { date: "2025-10-27", value: 0 },
       { date: "2025-10-28", value: 0 },
@@ -157,8 +210,51 @@ describe("monthMarkers — the leading-month suppression", () => {
     ];
     const cells = calendarGrid(days, "2025-11-05", null);
     expect(cells).toHaveLength(14);
-    // The partial October tail is unlabeled; November's Monday opens.
-    expect(monthMarkers(cells)).toEqual(["", "11"]);
+    const markers = monthMarkers(cells);
+    expect(markers).not.toContain("10");
+    expect(markers).toEqual(["11", ""]);
+  });
+
+  it("labels a month whose 1st falls mid-column, not one column late", () => {
+    // Grid starts Mon Sep 29; Oct 1 (a Wednesday) is in the head
+    // column. October is labeled THERE — the old Monday-opened rule
+    // pushed it to the next column.
+    const days: HkCalendarHeatmapDay[] = Array.from(
+      { length: 14 },
+      (_, i) => ({ date: shiftIso("2025-09-29", i), value: 0 }),
+    );
+    const cells = calendarGrid(days, "2025-10-12", null);
+    expect(cells).toHaveLength(14);
+    expect(monthMarkers(cells)).toEqual(["10", ""]);
+  });
+
+  it("labels a 1st the server shipped past a lead-clocked server (fix 5's boundary)", () => {
+    // The ONE way an unarrived 1st ends up labeled: the series shipped
+    // it, so fix 5 renders it a real day. A conforming server clamps its
+    // window to its own today, so this needs a server clock leading the
+    // client's — out of contract, and even then the chart is drawing a
+    // day that really carries data.
+    const shipped: HkCalendarHeatmapDay[] = [
+      { date: "2025-10-27", value: 0 },
+      { date: "2025-10-28", value: 0 },
+      { date: "2025-10-29", value: 0 },
+      { date: "2025-10-30", value: 0 },
+      { date: "2025-10-31", value: 0 },
+      { date: "2025-11-01", value: 2 },
+    ];
+    const cells = calendarGrid(shipped, "2025-10-29", null);
+    expect(cells.find((c) => c.date === "2025-11-01")).toMatchObject({
+      kind: "day",
+    });
+    // ...and the head column, which now carries November's 1st, labels it
+    // while still never labeling its own partial October.
+    expect(monthMarkers(cells)).toEqual(["11"]);
+
+    // The identical axis WITHOUT the shipped 1st: unarrived → unlabeled
+    // (the pair pins the boundary).
+    const unshipped: HkCalendarHeatmapDay[] = shipped.slice(0, 3);
+    const bare = calendarGrid(unshipped, "2025-10-29", null);
+    expect(monthMarkers(bare)).toEqual([""]);
   });
 
   it("labels no month when the whole grid sits inside one partial month", () => {
@@ -170,8 +266,44 @@ describe("monthMarkers — the leading-month suppression", () => {
     expect(monthMarkers(cells)).toEqual([""]);
   });
 
+  it("does not label a month that has not started yet (a future 1st in the padding)", () => {
+    // The axis pads to Sunday, so the column reaches Nov 1–2 while the
+    // series (and `today`) stop at Oct 29: those cells are unshipped
+    // future gaps. November holds no real day yet — labeling it would
+    // claim a month the chart does not show.
+    const days: HkCalendarHeatmapDay[] = Array.from(
+      { length: 3 },
+      (_, i) => ({ date: shiftIso("2025-10-27", i), value: 0 }),
+    );
+    const cells = calendarGrid(days, "2025-10-29", null);
+    expect(cells).toHaveLength(7);
+    expect(cells.find((c) => c.date === "2025-11-01")).toMatchObject({
+      kind: "gap",
+      phase: "after",
+    });
+    expect(monthMarkers(cells)).toEqual([""]);
+  });
+
+  it("still labels a 1st that fell before the account had data (a before gap)", () => {
+    // The suppression test is `after`, not "is a gap": a month the chart
+    // draws as unarrived is not labeled, while a PAST month the account
+    // has no data for is still an axis and keeps its label. Dropping the
+    // phase half of the check (`kind === "gap"`) would go green without
+    // this test.
+    const days: HkCalendarHeatmapDay[] = Array.from(
+      { length: 3 },
+      (_, i) => ({ date: shiftIso("2025-12-05", i), value: 0 }),
+    );
+    const cells = calendarGrid(days, "2025-12-07", "2025-12-02");
+    expect(cells.find((c) => c.date === "2025-12-01")).toMatchObject({
+      kind: "gap",
+      phase: "before",
+    });
+    expect(monthMarkers(cells)).toEqual(["12"]);
+  });
+
   it("keeps the later markers honest about consecutive same-month columns", () => {
-    // Two December Mondays: only the first carries the label.
+    // Two December Mondays: only the column carrying Dec 1 is labeled.
     const days: HkCalendarHeatmapDay[] = [
       { date: MON, value: 0 },
       { date: "2025-12-02", value: 0 },
@@ -187,4 +319,26 @@ describe("monthMarkers — the leading-month suppression", () => {
     const cells = calendarGrid(days, "2025-12-10", null);
     expect(monthMarkers(cells)).toEqual(["12", ""]);
   });
+
+  it("labels every month of a calendar year exactly once, on the column holding its 1st", () => {
+    const days: HkCalendarHeatmapDay[] = Array.from(
+      { length: 365 },
+      (_, i) => ({ date: shiftIso("2025-01-01", i), value: 0 }),
+    );
+    // Today = the series' last day, so the padded tail (Jan 1 2026) is
+    // still unarrived and carries no label.
+    const cells = calendarGrid(days, "2025-12-31", null);
+    const markers = monthMarkers(cells);
+    expect(markers.filter((m) => m !== "")).toEqual([
+      "1", "2", "3", "4", "5", "6", "7", "8", "9", "10", "11", "12",
+    ]);
+    // Each label sits on the column whose dates include that month's 1st.
+    markers.forEach((label, col) => {
+      if (!label) return;
+      const dates = cells.slice(col * 7, col * 7 + 7).map((c) => c.date);
+      expect(
+        dates.some((d) => d.slice(8, 10) === "01" && Number(d.slice(5, 7)) === Number(label)),
+      ).toBe(true);
+    });
+  });
 });

package/src/components/calendarHeatmap.ts

@@ -11,11 +11,39 @@
  * derivation is unit-testable without a component mount.
  */
 
-/** Opacity per bucket (0–4) over the primary token; bucket 0 is the
- * muted empty cell. Five steps so "no consumption" stays visually
- * distinct from "the smallest consumption on record". Exported for the
- * component and its tests — the scale is part of the contract. */
-export const HEATMAP_LEVEL_OPACITY = ["0.12", "0.22", "0.42", "0.66", "0.95"] as const;
+/** The empty cell (level 0) and the legend's first swatch fill: the
+ * muted token washed out so "no consumption" stays visually distinct
+ * from "the smallest consumption on record". Level 0 has no opacity
+ * step of its own — it may not be re-tinted by the primary token at
+ * all. */
+export const HEATMAP_EMPTY_FILL =
+  "color-mix(in srgb, var(--hi-color-muted) 40%, transparent)";
+
+/** Opacity per CONSUMING bucket (levels 1–4) over the primary token,
+ * four steps low → peak. The array is indexed by `level - 1` (level 0
+ * is `HEATMAP_EMPTY_FILL`, never an opacity step); the legend renders
+ * the empty swatch plus these four. Exported for the component and its
+ * tests — the scale is part of the contract. */
+export const HEATMAP_LEVEL_OPACITY = ["0.22", "0.42", "0.66", "0.95"] as const;
+
+/** The fill for one cell: level 0 carries the empty wash, every
+ * consuming level rides the primary token. The empty cell is never
+ * re-tinted primary and never takes an opacity step (the reference
+ * calendar this upstreaming followed draws it the same way), so the
+ * two channels stay independent — pinned as a helper because happy-dom
+ * drops `color-mix()` out of a parsed `background`. */
+export function heatmapCellFill(level: 0 | 1 | 2 | 3 | 4): string {
+  return level === 0 ? HEATMAP_EMPTY_FILL : "var(--hi-color-primary)";
+}
+
+/** The opacity step for one cell: level 0 has none (its wash is the
+ * fill), consuming levels index [`HEATMAP_LEVEL_OPACITY`] by
+ * `level - 1`. */
+export function heatmapCellOpacity(
+  level: 0 | 1 | 2 | 3 | 4,
+): string | undefined {
+  return level === 0 ? undefined : HEATMAP_LEVEL_OPACITY[level - 1];
+}
 
 /** One input day of the dense series. `value` may be negative or zero
  * (a "no consumption" day) — it still buckets to level 0. */
@@ -81,7 +109,15 @@ export function calendarGrid(
   const cells: CalendarCell[] = [];
   for (let i = 0; i < span; i++) {
     const date = shiftIso(gridStart, i);
-    if (date > today) {
+    // Never hatch a date the server actually shipped: a series whose
+    // last row runs past `today` (a skewed server clock, out of
+    // contract) would otherwise render EVERY one of its days as a
+    // future gap — the data would vanish behind the hatch. (The
+    // before-first hatch below deliberately does NOT consult the map:
+    // the server fills the pre-anchor stretch with dense zeros as
+    // filler, and the account's first-activity anchor is what decides
+    // that no data existed, however many filler rows arrive.)
+    if (date > today && !valueByDate.has(date)) {
       cells.push({ kind: "gap", date, phase: "after" });
       continue;
     }
@@ -108,32 +144,51 @@ export function bucketLevel(value: number, max: number): 0 | 1 | 2 | 3 | 4 {
 }
 
 /**
- * Month markers for the week columns: a short label on each column
- * whose Monday opens a month, "" otherwise.
+ * Month markers for the week columns: a short label over the column
+ * that CONTAINS a month's first day (the 1st), "" otherwise.
+ *
+ * The leading-month rule (2026-10 user direction) falls out of this
+ * anchor instead of being a special case: a trailing-year window
+ * usually starts MID-month, so the head column carries only that
+ * month's tail — the head month's 1st is not in the grid, so it is
+ * never labeled. A month whose 1st IS on the axis is labeled on the
+ * column showing it (which may be mid-column rather than the next
+ * Monday), so no label lands one column late.
  *
- * The leading month is the 2026-10 refinement this extraction carries:
- * a trailing-year window (or any window) usually starts MID-month, so
- * the first column shows only the tail of its month. A label there
- * would claim a month whose start is not visible on the chart — the
- * GitHub convention is to suppress it. The first marker is therefore
- * shown ONLY when the grid's first column actually opens its month
- * (its Monday is the 1st); every later marker keeps the previous
- * rule (this column's Monday opens a month the previous column's
- * Monday did not). Every grid cell carries a real calendar date, so
- * the marker can never lie about padding.
+ * The one suppression is the unarrived tail: the padded axis may reach
+ * into next month's first days as "after" cells, and a 1st the chart
+ * itself renders as unarrived carries no label — a label there would
+ * announce a month the chart does not draw yet. The test rides the
+ * cell's PHASE, not its data: a 1st the server shipped is a real day
+ * and labels normally (only a server whose clock leads the client's,
+ * out of contract, can ship one), and a past month the account has no
+ * data for at all is still an axis the chart draws, so it keeps its
+ * label. Every grid cell carries a real calendar date, so the marker
+ * can never lie about padding.
  */
 export function monthMarkers(cells: CalendarCell[]): string[] {
   const weeks = Math.ceil(cells.length / 7);
   const markers: string[] = [];
-  let prevMonth = -1;
+  // `lastFirstMonth` is belt-and-braces for callers that hand this helper
+  // a sparse or hand-built cell list: a contiguous axis never carries a
+  // month's 1st twice (a 7-day column holds at most one "01"), so on
+  // calendarGrid output the guard never fires. It mirrors the reference
+  // grid's own `labeledMonth` dedup.
+  let lastFirstMonth = -1;
   for (let w = 0; w < weeks; w++) {
-    const monday = cells[w * 7];
-    if (!monday) break;
-    const month = Number(monday.date.slice(5, 7));
-    const opensMonth =
-      w === 0 ? monday.date.slice(8, 10) === "01" : month !== prevMonth;
-    markers.push(opensMonth ? String(month) : "");
-    prevMonth = month;
+    let month = -1;
+    for (let d = 0; d < 7; d++) {
+      const cell = cells[w * 7 + d];
+      if (!cell) break;
+      const isMonthStart = cell.date.slice(8, 10) === "01";
+      const isFuture = cell.kind === "gap" && cell.phase === "after";
+      if (isMonthStart && !isFuture) {
+        month = Number(cell.date.slice(5, 7));
+        break;
+      }
+    }
+    markers.push(month !== -1 && month !== lastFirstMonth ? String(month) : "");
+    if (month !== -1) lastFirstMonth = month;
   }
   return markers;
 }

package/src/index.ts

@@ -660,6 +660,9 @@ export { default as HCalendarHeatmap } from "./components/HkCalendarHeatmap";
 export {
   bucketLevel,
   calendarGrid,
+  heatmapCellFill,
+  heatmapCellOpacity,
+  HEATMAP_EMPTY_FILL,
   HEATMAP_LEVEL_OPACITY,
   monthMarkers,
   todayIso,