@celestia-island/hikari 0.55.330 → 0.55.332

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celestia-island/hikari",
-  "version": "0.55.330",
+  "version": "0.55.332",
   "private": false,
   "type": "module",
   "description": "Hikari UI library, Vue 3 runtime — one design system for Vue 3 and Rust/WASM applications",
@@ -62,23 +62,23 @@
     "prepublishOnly": "vue-tsc --noEmit"
   },
   "peerDependencies": {
-    "@types/three": "^*",
+    "@types/three": "^0.185",
     "three": "^0.185",
-    "vue": "^*"
+    "vue": "^3"
   },
   "dependencies": {
-    "@celestia-island/tairitsu-transport": "^0.2.0",
-    "@xterm/addon-fit": "^0.*",
+    "@celestia-island/tairitsu-transport": "^0.2",
+    "@xterm/addon-fit": "^0.11",
     "@xterm/addon-image": "^0.10.0-beta.301",
     "@xterm/xterm": "^6.1.0-beta.304",
-    "dompurify": "^*",
-    "highlight.js": "^*",
-    "lucide-vue-next": "^*",
-    "marked": "^*"
+    "dompurify": "^3",
+    "highlight.js": "^11",
+    "lucide-vue-next": "^1",
+    "marked": "^18"
   },
   "devDependencies": {
     "@types/node": "^*",
-    "@types/three": "^*",
+    "@types/three": "^0.185",
     "@vitejs/plugin-vue": "^*",
     "@vitejs/plugin-vue-jsx": "^*",
     "@vue/server-renderer": "^*",

package/src/components/HkCalendarHeatmap.scss

@@ -131,4 +131,15 @@
   &-grid {
     display: grid;
   }
+
+  // The shared cell tooltip's content area. The popup chrome (bubble,
+  // shadow, placement geometry) is HkTooltip's .hk-tooltip-popup — the
+  // heatmap only frames the caller's slot content, usually one row per
+  // model with the metering readout on the right.
+  &-tip {
+    display: flex;
+    flex-direction: column;
+    gap: 4px;
+    min-width: 140px;
+  }
 }

package/src/components/HkCalendarHeatmap.test.tsx

@@ -5,8 +5,17 @@ import { fileURLToPath } from "node:url";
 import { afterEach, describe, expect, it, vi } from "vitest";
 import { createApp, defineComponent, h, nextTick, reactive } from "vue";
 
-import HkCalendarHeatmap from "./HkCalendarHeatmap";
-import { HEATMAP_LEVEL_OPACITY, shiftIso } from "./calendarHeatmap";
+import HkCalendarHeatmap, {
+  HEATMAP_GAP_FILL,
+  TOOLTIP_DELAY_MS,
+} from "./HkCalendarHeatmap";
+import { HEATMAP_EMPTY_FILL, HEATMAP_LEVEL_OPACITY, shiftIso, type CalendarCell } from "./calendarHeatmap";
+
+/** The shared hover popup's show delay rides the component's EXPORTED
+ * constant (R5: the old duplicated literal let a shorter delay ship
+ * green — the tests must DERIVE, not restate). The behavioral pin
+ * lives in the hover test: hidden at delay−1, visible at delay. */
+expect(HEATMAP_GAP_FILL).not.toContain("gradient");
 
 const here = dirname(fileURLToPath(import.meta.url));
 
@@ -237,9 +246,9 @@ describe("HkCalendarHeatmap", () => {
     expect(cellAt("0").style.opacity).toBe("");
   });
 
-  it("renders gap cells hatched and inert (no tooltip, no level claim)", () => {
+  it("renders gap cells dimmed below the empty level, with 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
+    // padding dims 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
@@ -266,13 +275,213 @@ describe("HkCalendarHeatmap", () => {
       for (const gap of gaps) {
         expect(gap.getAttribute("aria-hidden")).toBe("true");
         expect(gap.getAttribute("title")).toBeNull();
-        expect(gap.style.pointerEvents).toBe("none");
+        // The 2026-11 direction: the diagonal hatch is GONE — a gap
+        // claims no gradient, no level, no primary ink. (The fill's
+        // VALUE rides HEATMAP_GAP_FILL — happy-dom drops color-mix()
+        // from a parsed background, so the constant itself is pinned
+        // at this file's head and by the source contract below.)
+        expect(gap.getAttribute("style") ?? "").not.toContain("gradient");
+        expect(gap.getAttribute("style") ?? "").not.toContain("--hi-color-primary");
+        expect(gap.getAttribute("data-level")).toBeNull();
+        // The ladder must read gap < empty < data (R2 2026-11): the
+        // dimmed wash sits BELOW the empty level's wash, parsed from
+        // the two exported constants so a percentage drift on either
+        // side flips this even with every other gate green.
+        const pct = (fill: string) =>
+          Number(/(\d+)%/.exec(fill)?.[1] ?? NaN);
+        expect(pct(HEATMAP_GAP_FILL)).toBeLessThan(pct(HEATMAP_EMPTY_FILL));
       }
     } finally {
       vi.useRealTimers();
     }
   });
 
+  it("paints gap cells with HEATMAP_GAP_FILL, not a hatch (source contract)", () => {
+    // happy-dom cannot observe the gap fill through a parsed style, so
+    // this pin reads the sheet's wiring: the gap branch of cellStyle
+    // must carry the exported dimmed-wash constant — a re-introduced
+    // repeating-linear-gradient hatch (or a hand-written fill) turns
+    // this red.
+    const sheet = readFileSync(join(here, "HkCalendarHeatmap.tsx"), "utf8");
+    expect(sheet).not.toContain("repeating-linear-gradient");
+    expect(sheet).toContain("background: HEATMAP_GAP_FILL");
+  });
+
+  it("without a tooltip slot, day cells keep the native title and no popup ever mounts", async () => {
+    vi.useFakeTimers();
+    try {
+      const c = mount(
+        h(HkCalendarHeatmap, {
+          days: daysFrom(CLEAN_HEAD_MON, 1, 5),
+          first: null,
+        }),
+      );
+      const cell = c.querySelector('[data-level]:not([data-level="0"])') as HTMLElement;
+      expect(cell.getAttribute("title")).toContain("Dec 1, 2025");
+      cell.dispatchEvent(new Event("pointerover", { bubbles: true }));
+      await vi.advanceTimersByTimeAsync(TOOLTIP_DELAY_MS);
+      await nextTick();
+      expect(document.querySelector(".hk-calendar-heatmap-tip")).toBeNull();
+      // The old contract stands in full: the gaps stay INERT (R2 2026-11
+      // restore — the dimmed wash is presentational, and without a slot
+      // nothing can ever engage them). The 5-day fixture spans a whole
+      // week, so a guaranteed-gap mount (one day + first anchor) pins it.
+      const inert = mount(
+        h(HkCalendarHeatmap, {
+          days: [{ date: "2025-12-03", value: 5 }],
+          first: "2025-12-03",
+        }),
+      );
+      const gap = inert.querySelector("[data-gap]") as HTMLElement;
+      expect(gap.style.pointerEvents).toBe("none");
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it("with a tooltip slot, hovering a day cell opens the shared popup with the caller's content", async () => {
+    vi.useFakeTimers();
+    try {
+      const c = mount(
+        h(HkCalendarHeatmap, {
+          days: daysFrom(CLEAN_HEAD_MON, 1, 5),
+          first: null,
+        }, {
+          tooltip: ({ cell }: { cell: CalendarCell }) =>
+            h("div", { "data-tip-for": cell.date }, `tip:${cell.kind}`),
+        }),
+      );
+      // The slot owns the explanation: no native title (it would double
+      // up under the popup).
+      const cell = c.querySelector('[data-level]:not([data-level="0"])') as HTMLElement;
+      expect(cell.getAttribute("title")).toBeNull();
+
+      // Lazy: nothing is teleported until the first engage.
+      expect(document.querySelector(".hk-calendar-heatmap-tip")).toBeNull();
+      cell.dispatchEvent(new Event("pointerover", { bubbles: true }));
+      // Behavioral lower bound (R5): the popup is NOT visible one
+      // millisecond before the delay — the tests derive the window
+      // from the exported constant, so a shorter delay ships red.
+      await vi.advanceTimersByTimeAsync(TOOLTIP_DELAY_MS - 1);
+      await nextTick();
+      const early = document.querySelector(
+        ".hk-calendar-heatmap-tip.hk-tooltip-visible",
+      );
+      expect(early, "no visible popup before the delay elapses").toBeNull();
+      await vi.advanceTimersByTimeAsync(1);
+      await nextTick();
+      const popup = document.querySelector(
+        ".hk-calendar-heatmap-tip",
+      ) as HTMLElement | null;
+      expect(popup, "the shared popup is up after the delay").not.toBeNull();
+      expect(popup!.getAttribute("role")).toBe("tooltip");
+      expect(popup!.textContent).toBe("tip:day");
+      expect(popup!.querySelector('[data-tip-for="2025-12-01"]')).not.toBeNull();
+      expect(popup!.classList.contains("hk-tooltip-visible")).toBe(true);
+
+      // Leaving the grid hides it (the popup element stays mounted —
+      // lazy on FIRST engage, not per hover).
+      const grid = c.querySelector('[data-testid="hk-calendar-heatmap"]') as HTMLElement;
+      grid.dispatchEvent(new Event("pointerleave", { bubbles: false }));
+      await nextTick();
+      expect(
+        document.querySelector(".hk-calendar-heatmap-tip")!.classList.contains("hk-tooltip-visible"),
+      ).toBe(false);
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it("the tooltip slot also fires for gap cells — the caller explains 'no data'", async () => {
+    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",
+        }, {
+          tooltip: ({ cell }: { cell: CalendarCell }) =>
+            h("div", { "data-tip-kind": cell.kind }, JSON.stringify(cell)),
+        }),
+      );
+      const grid = c.querySelector('[data-testid="hk-calendar-heatmap"]') as HTMLElement;
+      const gap = grid.querySelector("[data-gap]") as HTMLElement;
+      // With the slot the gaps are the popup's engage surface: they
+      // must stay hoverable (synthetic events bypass hit-testing, so
+      // only this pin catches a regression to unconditional none).
+      expect(gap.style.pointerEvents).not.toBe("none");
+      gap.dispatchEvent(new Event("pointerover", { bubbles: true }));
+      await vi.advanceTimersByTimeAsync(TOOLTIP_DELAY_MS);
+      await nextTick();
+      const popup = document.querySelector(".hk-calendar-heatmap-tip") as HTMLElement;
+      const payload = JSON.parse(
+        popup.querySelector("[data-tip-kind]")!.textContent ?? "{}",
+      );
+      expect(payload).toMatchObject({ kind: "gap", date: gap.getAttribute("data-date") });
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it("a touch pointerleave does not close what a tap opened; a desktop leave does", async () => {
+    // Browsers fire the boundary-release chain (pointerleave on the
+    // tapped cell) right after a touch pointerup — implicit capture
+    // release. The tap-toggle owns touch dismissal, so that synthetic
+    // leave must NOT hide the popup (R2 2026-11; the mouse leave path
+    // stays). happy-dom does not model the implicit release, which is
+    // exactly why this needs its own pin.
+    vi.useFakeTimers();
+    try {
+      const c = mount(
+        h(HkCalendarHeatmap, {
+          days: daysFrom(CLEAN_HEAD_MON, 1, 5),
+          first: null,
+        }, {
+          tooltip: ({ cell }: { cell: CalendarCell }) =>
+            h("div", { "data-tip-for": cell.date }, `tip:${cell.kind}`),
+        }),
+      );
+      const cell = c.querySelector('[data-level]:not([data-level="0"])') as HTMLElement;
+      const grid = c.querySelector('[data-testid="hk-calendar-heatmap"]') as HTMLElement;
+
+      // A touch tap arms + shows at once.
+      cell.dispatchEvent(new PointerEvent("pointerdown", { bubbles: true, pointerType: "touch" }));
+      await nextTick();
+      const popup = () => document.querySelector(".hk-calendar-heatmap-tip") as HTMLElement | null;
+      expect(popup()!.classList.contains("hk-tooltip-visible")).toBe(true);
+
+      // The implicit-release leave: same gesture, must not hide.
+      grid.dispatchEvent(new PointerEvent("pointerleave", { pointerType: "touch" }));
+      await nextTick();
+      expect(popup()!.classList.contains("hk-tooltip-visible")).toBe(true);
+
+      // A mouse (pointerType-less event reads undefined) leave hides.
+      grid.dispatchEvent(new PointerEvent("pointerleave", {}));
+      await nextTick();
+      expect(popup()!.classList.contains("hk-tooltip-visible")).toBe(false);
+
+      // The tap-toggle owns touch dismissal, so BOTH directions stay
+      // pinned: a second tap on the SAME cell closes it…
+      cell.dispatchEvent(new PointerEvent("pointerdown", { bubbles: true, pointerType: "touch" }));
+      await nextTick();
+      expect(popup()!.classList.contains("hk-tooltip-visible")).toBe(true);
+      cell.dispatchEvent(new PointerEvent("pointerdown", { bubbles: true, pointerType: "touch" }));
+      await nextTick();
+      expect(popup()!.classList.contains("hk-tooltip-visible")).toBe(false);
+
+      // …and a tap OUTSIDE the grid dismisses a re-opened tooltip.
+      cell.dispatchEvent(new PointerEvent("pointerdown", { bubbles: true, pointerType: "touch" }));
+      await nextTick();
+      expect(popup()!.classList.contains("hk-tooltip-visible")).toBe(true);
+      document.body.dispatchEvent(new PointerEvent("pointerdown", { bubbles: true, pointerType: "touch" }));
+      await nextTick();
+      expect(popup()!.classList.contains("hk-tooltip-visible")).toBe(false);
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
   it("tooltips day cells with the unit when one is given", () => {
     const c = mount(
       h(HkCalendarHeatmap, {

package/src/components/HkCalendarHeatmap.tsx

@@ -1,6 +1,9 @@
-import { computed, defineComponent, ref, watch, type PropType } from "vue";
+import { computed, defineComponent, onBeforeUnmount, ref, Teleport, watch, type PropType, type SlotsType } from "vue";
 
 import { useI18n } from "../i18n/context";
+import { usePopupManager, type PopupHandle } from "../runtime/usePopupManager";
+import { applyTooltipPosition } from "../runtime/tooltipPosition";
+import { ensureOverlayRoot } from "../overlay/overlayRoot";
 import HkScrollContainer from "./HkScrollContainer";
 import {
   calendarGrid,
@@ -20,10 +23,23 @@ import "./HkCalendarHeatmap.scss";
 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. */
-const GAP_HATCH =
-  "repeating-linear-gradient(45deg, color-mix(in srgb, var(--hi-color-muted) 70%, transparent) 0px, color-mix(in srgb, var(--hi-color-muted) 70%, transparent) 2px, transparent 2px, transparent 4px)";
+ * today): a quiet, recessed wash — the muted token at a fainter
+ * strength than the EMPTY level's wash (40%), so the visual ladder
+ * reads gap < empty < data with no third channel. (2026-11 user
+ * direction: the old diagonal hatch read as noise at a year-wide
+ * grid's density — a flat dimmer cell carries the same "no data yet"
+ * claim without the stripes.) Deliberately NOT pointer-inert: with a
+ * `tooltip` slot the caller also explains gaps ("the account has no
+ * data for this date"), so cells stay hover targets. */
+export const HEATMAP_GAP_FILL =
+  "color-mix(in srgb, var(--hi-color-muted) 20%, transparent)";
+
+/** The hover tooltip's show delay — HkTooltip's default, so the two
+ * hover surfaces in a page share one cadence. */
+/** The hover tooltip's show delay — HkTooltip's default, so the two
+ * hover surfaces in a page share one cadence. Exported so consumers
+ * (and the tests) derive from it instead of duplicating the literal. */
+export const TOOLTIP_DELAY_MS = 300;
 
 /** Minimal {name} interpolation for the component's i18n strings — the
  * hikari context serves plain strings (no ICU), the placeholders stay
@@ -32,6 +48,12 @@ function fill(template: string, vars: Record<string, string | number>): string {
   return template.replace(/\{(\w+)\}/g, (_, k: string) => String(vars[k] ?? ""));
 }
 
+/** Stable per-instance popup id. The popup carries role="tooltip" and
+ * this id; callers' slot content that wants an aria-describedby link
+ * can reference it, but the component binds no describedby itself —
+ * the armed cell is a delegated span, not a managed wrapper. */
+let popupSeq = 0;
+
 /**
  * HkCalendarHeatmap — a GitHub-style calendar heatmap of daily values.
  *
@@ -40,7 +62,7 @@ function fill(template: string, vars: Record<string, string | number>): string {
  * component — the rich-text-viewer table — and the leading-month
  * marker refinement belongs in the library, not the consumer). A
  * legend (less → more over the primary token), a Monday-first weekday
- * rail, month markers, and hatched no-data gap cells that never claim
+ * rail, month markers, and dimmed no-data gap cells that never claim
  * a fake zero.
  *
  * The leading month is never mislabeled: a month is labeled on the
@@ -55,6 +77,15 @@ function fill(template: string, vars: Record<string, string | number>): string {
  * its own tests). The `toolbar` slot rides right of the legend — the
  * consumer's range tabs / controls belong there.
  *
+ * Tooltips (2026-11 user direction): every cell — day AND gap — carries
+ * a caller-decided tooltip through the `tooltip` slot (payload
+ * `{ cell }`, the same `CalendarCell` the grid renders). The component
+ * owns the machinery (one lazy, teleported hover popup in the shared
+ * HkTooltip chrome, re-anchored per frame while visible) so a caller
+ * never mounts ~370 popup instances; it decides only the CONTENT.
+ * Without the slot the old behaviour stands: day cells keep their
+ * native `title`, gap cells stay silent.
+ *
  * Scrolling (2026-11-08): the calendar body rides HkScrollContainer
  * (axis="horizontal", align="center") so the strip uses hikari's own
  * auto-hiding overlay scrollbar and NEVER a native bar — a chart that
@@ -95,6 +126,14 @@ export default defineComponent({
      *  contract. Pass "start" to restore the old GitHub-style origin. */
     anchor: { type: String as PropType<"start" | "end">, default: "end" },
   },
+  slots: Object as SlotsType<{
+    /** Right of the legend: the consumer's range tabs / controls. */
+    toolbar?: (props: Record<string, never>) => unknown;
+    /** One cell's tooltip content. Fires for day AND gap cells; the
+     *  component renders it in a single shared hover popup (the
+     *  HkTooltip chrome), re-anchored to the hovered cell per frame. */
+    tooltip?: (props: { cell: CalendarCell }) => unknown;
+  }>,
   setup(props, { slots }) {
     const { t } = useI18n();
 
@@ -155,12 +194,174 @@ export default defineComponent({
         { date: dateLabel(d.date), n: d.value, unit: props.unit },
       );
 
+    // ── the caller-decided cell tooltip ────────────────────────────────
+    // One shared popup for the whole grid (HkTooltip's chrome and lazy
+    // machinery) — a caller slot decides the CONTENT per cell; the
+    // component never mounts per-cell popup instances. Inactive unless
+    // the slot is present: without it, day cells keep their native
+    // `title` and gap cells stay silent (the pre-tooltip contract).
+    const hasTooltipSlot = computed(() => !!slots.tooltip);
+
+    // date → cell lookup for the delegated hover (cells already carry
+    // data-date; no extra attributes on the grid's 370 spans).
+    const cellByDate = computed(() => {
+      const map = new Map<string, CalendarCell>();
+      for (const cell of cells.value) map.set(cell.date, cell);
+      return map;
+    });
+
+    const tip = ref<{ cell: CalendarCell; el: HTMLElement } | null>(null);
+    const tipVisible = ref(false);
+    const tipPopupId = `hk-calendar-heatmap-tip-${++popupSeq}`;
+    const tipManager = usePopupManager();
+    let tipHandle: PopupHandle | null = null;
+    const tipZIndex = ref<number | null>(null);
+    const tipEverShown = ref(false);
+    let tipShowTimer: ReturnType<typeof setTimeout> | null = null;
+    let tipPositionFrame: number | null = null;
+    let tipArmedCell: string | null = null;
+
+    function tipEngage() {
+      if (tipEverShown.value) return;
+      tipEverShown.value = true;
+      if (!tipHandle) tipHandle = tipManager.register("tooltip", false);
+      tipZIndex.value = tipHandle.zIndex;
+    }
+
+    function tipStopTracking() {
+      if (tipPositionFrame !== null) cancelAnimationFrame(tipPositionFrame);
+      tipPositionFrame = null;
+    }
+
+    function tipUpdatePosition() {
+      if (!tip.value || !popupRef.value) return;
+      applyTooltipPosition(popupRef.value, tip.value.el.getBoundingClientRect(), "top");
+    }
+
+    function tipTrackWhileVisible() {
+      if (tipPositionFrame !== null) return;
+      const tick = () => {
+        tipPositionFrame = null;
+        if (!tipVisible.value) return;
+        // The hovered cell can move without a pointer event (the strip's
+        // horizontal scroll) — re-read its rect per frame while visible.
+        tipUpdatePosition();
+        tipPositionFrame = requestAnimationFrame(tick);
+      };
+      tipPositionFrame = requestAnimationFrame(tick);
+    }
+
+    function tipShowNow() {
+      if (tipShowTimer !== null) {
+        clearTimeout(tipShowTimer);
+        tipShowTimer = null;
+      }
+      tipVisible.value = true;
+      tipTrackWhileVisible();
+    }
+
+    function tipHide() {
+      if (tipShowTimer !== null) {
+        clearTimeout(tipShowTimer);
+        tipShowTimer = null;
+      }
+      tipArmedCell = null;
+      tipVisible.value = false;
+      tipStopTracking();
+    }
+
+    /** The cell a pointer event landed on (delegated: the spans carry
+     *  data-date; find the closest one from the event target). */
+    function cellFromEvent(e: Event): { cell: CalendarCell; el: HTMLElement } | null {
+      const target = e.target as HTMLElement | null;
+      const span = target?.closest?.("[data-date]") as HTMLElement | null;
+      if (!span) return null;
+      const date = span.getAttribute("data-date");
+      if (!date) return null;
+      const cell = cellByDate.value.get(date);
+      return cell ? { cell, el: span } : null;
+    }
+
+    function onGridPointerover(e: PointerEvent) {
+      if (!hasTooltipSlot.value) return;
+      if (performance.now() - lastTouchAt < 600) return;
+      const hit = cellFromEvent(e);
+      if (!hit) return;
+      if (tipArmedCell === hit.cell.date) return;
+      tipArmedCell = hit.cell.date;
+      tip.value = hit;
+      tipEngage();
+      // Cell→cell travel with the popup already up swaps content in
+      // place (no hide/show flicker); a cold hover waits the delay.
+      if (tipVisible.value) tipShowNow();
+      else {
+        if (tipShowTimer !== null) clearTimeout(tipShowTimer);
+        tipShowTimer = setTimeout(tipShowNow, TOOLTIP_DELAY_MS);
+      }
+    }
+
+    function onGridPointerleave(e: PointerEvent) {
+      if (!hasTooltipSlot.value) return;
+      // Touch's tap-toggle owns dismissal: the boundary-release chain
+      // after a touch pointerup fires pointerleave on the tapped cell
+      // in the same gesture (implicit capture release), which would
+      // close the tooltip the tap just opened (R2). Desktop leave hides.
+      if (e.pointerType === "touch") return;
+      tipHide();
+    }
+
+    // Touch has no hover: a tap arms the tooltip for that cell at once,
+    // and a tap anywhere else dismisses it (the outside-listener lives
+    // only while a touch tip is up).
+    let lastTouchAt = -Infinity;
+    const popupRef = ref<HTMLElement | null>(null);
+    const gridRef = ref<HTMLElement | null>(null);
+    function onOutsideTap(e: PointerEvent) {
+      const target = e.target as HTMLElement | null;
+      if (gridRef.value?.contains(target ?? null)) return;
+      tipHide();
+      document.removeEventListener("pointerdown", onOutsideTap, true);
+    }
+
+    function onGridPointerdown(e: PointerEvent) {
+      if (!hasTooltipSlot.value || e.pointerType === "mouse") return;
+      lastTouchAt = performance.now();
+      const hit = cellFromEvent(e);
+      if (!hit) return;
+      if (tipVisible.value && tipArmedCell === hit.cell.date) {
+        tipHide();
+        document.removeEventListener("pointerdown", onOutsideTap, true);
+        return;
+      }
+      tipArmedCell = hit.cell.date;
+      tip.value = hit;
+      tipEngage();
+      tipShowNow();
+      document.removeEventListener("pointerdown", onOutsideTap, true);
+      document.addEventListener("pointerdown", onOutsideTap, true);
+    }
+
+    onBeforeUnmount(() => {
+      tipHide();
+      document.removeEventListener("pointerdown", onOutsideTap, true);
+      if (tipHandle) {
+        tipManager.unregister(tipHandle.id);
+        tipHandle = null;
+      }
+    });
+
     const cellStyle = (cell: CalendarCell) =>
       cell.kind === "gap"
         ? {
             borderRadius: "3px",
-            background: GAP_HATCH,
-            pointerEvents: "none" as const,
+            background: HEATMAP_GAP_FILL,
+            // The dimmed wash is presentational, but without a tooltip
+            // slot the gaps stay INERT exactly as before (R2): with the
+            // slot they must stay hoverable — they are the popup's
+            // engage surface.
+            pointerEvents: hasTooltipSlot.value
+              ? undefined
+              : ("none" as const),
           }
         : {
             borderRadius: "3px",
@@ -298,8 +499,12 @@ export default defineComponent({
                 ))}
               </div>
 
-              {/* The grid itself: cells flow column-first into 7 rows. */}
+              {/* The grid itself: cells flow column-first into 7 rows.
+               * Hover is delegated on the grid (cells carry data-date);
+               * with a `tooltip` slot every cell — gaps included — is a
+               * live hover target for the shared popup below. */}
               <div
+                ref={gridRef}
                 data-testid="hk-calendar-heatmap"
                 data-max={max.value}
                 role="img"
@@ -317,6 +522,9 @@ export default defineComponent({
                   gridAutoFlow: "column",
                   gap: `${props.cellGap}px`,
                 }}
+                onPointerover={onGridPointerover}
+                onPointerleave={onGridPointerleave}
+                onPointerdown={onGridPointerdown}
               >
                 {cells.value.map((cell, i) => (
                   <span
@@ -330,7 +538,10 @@ export default defineComponent({
                       : {
                           "data-level": cell.level,
                           "data-date": cell.date,
-                          title: cellTitle(cell),
+                          // With a tooltip slot the shared popup owns the
+                          // cell's explanation — a native `title` would
+                          // double up on hover (and never fires for gaps).
+                          title: hasTooltipSlot.value ? undefined : cellTitle(cell),
                         })}
                     style={cellStyle(cell)}
                   />
@@ -339,6 +550,31 @@ export default defineComponent({
             </div>
           </div>
         </HkScrollContainer>
+
+        {/* The shared cell tooltip: one lazy popup for the whole grid,
+         * teleported to the overlay root and pinned to the hovered cell
+         * with the shared HkTooltip geometry (zoom-aware, clamped,
+         * pixel-snapped). Content is the caller's `tooltip` slot for
+         * `tip.cell`; the popup mounts on first engage and stays until
+         * unmount so re-shows never churn. */}
+        <Teleport to={ensureOverlayRoot()}>
+          {tipEverShown.value && tip.value && (
+            <div
+              ref={popupRef}
+              id={tipPopupId}
+              role="tooltip"
+              class={[
+                "hk-tooltip-popup",
+                "hk-tooltip-top",
+                tipVisible.value ? "hk-tooltip-visible" : "",
+                "hk-calendar-heatmap-tip",
+              ]}
+              style={tipZIndex.value != null ? { zIndex: tipZIndex.value } : {}}
+            >
+              {slots.tooltip?.({ cell: tip.value.cell })}
+            </div>
+          )}
+        </Teleport>
       </div>
     );
   },

package/src/components/HkFilterChip.scss

@@ -5,16 +5,22 @@
  * bare alpha tint — a lone chip over wallpaper reads as a hole).
  */
 
+/* Both flex links must be allowed to shrink below their content or the
+ * chip's text truncation never arms: min-width:auto would keep the chip
+ * at its nowrap min-content width forever. With no consumer width bound
+ * the chip simply renders at its natural width. */
 .hk-filter-chip-anchor {
   position: relative;
   display: inline-flex;
   align-items: center;
+  min-width: 0;
 }
 
 .hk-filter-chip {
   display: inline-flex;
   align-items: center;
   gap: var(--space-6);
+  min-width: 0;
   /* Vertical padding = trigger padding + one track step: the chip shares
    * its row with segmented HkTabs-style chrome, whose track adds
    * var(--space-2) around its triggers (the wowsp filter bar's alignment
@@ -60,6 +66,15 @@
   }
 }
 
+/* Long filter values ellipsize once a consumer bounds the row (both
+ * flex links above unlock shrinking); unbounded, the chip renders at
+ * its natural nowrap width and nothing truncates. */
+.hk-filter-chip-text {
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
 .hk-filter-chip-caret {
   opacity: 0.6;
   flex: 0 0 auto;

package/src/components/HkFilterPanel.scss

@@ -228,6 +228,12 @@
 
 /* Keyboard highlight face — identical values to the popup-select item's
  * [data-highlighted]; hover comes from mi.item's own guarded :hover. */
+/* The add row's label rides the shared menu-item label grammar
+ * (flex fill, optical offset, italic cushion, ellipsis). */
+.hk-filter-add-item-label {
+  @include mi.label;
+}
+
 .hk-filter-add-item[data-highlighted] {
   background: var(--c-primary-subtle, rgb(var(--color-primary) / 8%));
   border-color: var(--c-primary-medium, rgb(var(--color-primary) / 25%));

package/src/components/HkFilterTrigger.scss

@@ -12,6 +12,13 @@
   align-items: center;
 }
 
+/* Popup body: the panel and the mobile confirm footer stack in one
+ * column (the panel owns its own bounded width). */
+.hk-filter-trigger-body {
+  display: flex;
+  flex-direction: column;
+}
+
 .hk-filter-trigger-footer {
   display: flex;
   justify-content: flex-end;

package/src/components/calendarHeatmap.test.ts

@@ -114,7 +114,7 @@ describe("calendarGrid", () => {
     expect(cells[6]).toMatchObject({ kind: "gap", phase: "after" });
   });
 
-  it("hatches the before-first region and never claims a fake zero", () => {
+  it("dims the before-first region and never claims a fake zero", () => {
     const cells = calendarGrid(
       [{ date: "2025-12-05", value: 5 }],
       "2025-12-07",
@@ -138,7 +138,7 @@ describe("calendarGrid", () => {
     expect(cells[1]).toMatchObject({ kind: "day", date: "2025-12-02", level: 0 });
   });
 
-  it("clamps a malformed future `first` to hatch nothing", () => {
+  it("clamps a malformed future `first` to dim nothing", () => {
     const cells = calendarGrid(
       [{ date: MON, value: 5 }],
       "2025-12-03",
@@ -151,10 +151,10 @@ describe("calendarGrid", () => {
     expect(calendarGrid([], "2025-12-03", null)).toEqual([]);
   });
 
-  it("never hatches a day the server shipped, even past a skewed `today`", () => {
+  it("never dims 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
+    // day of the series vanishing behind the "after" dim is the
     // failure mode this guards.
     const cells = calendarGrid(
       [
@@ -169,7 +169,7 @@ describe("calendarGrid", () => {
       value: 3,
       level: 3,
     });
-    // The unshipped padding past it still hatches.
+    // The unshipped padding past it still dims.
     expect(cells.find((c) => c.date === "2025-12-03")).toMatchObject({
       kind: "gap",
       phase: "after",

package/src/components/calendarHeatmap.ts

@@ -7,7 +7,7 @@
  * The server ships a DENSE daily series (oldest → newest, zero-filled,
  * inclusive of today, plus the account's first activity date).
  * Everything the component renders — the full-year week grid with its
- * hatched no-data gaps, the month markers — derives here so each
+ * dimmed no-data gaps, the month markers — derives here so each
  * derivation is unit-testable without a component mount.
  */
 
@@ -71,8 +71,9 @@ export function todayIso(): string {
 /**
  * One heatmap cell: a real day of the series, or a gap the account has
  * no data for — before its first activity, or after today (the rest of
- * the always-full-year window). Gaps render hatched and inert; they
- * never claim a fake "0 consumption" for a day that never was.
+ * the always-full-year window). Gaps render as the dimmed no-data wash
+ * (the gap channel sits BELOW the empty level); they never claim a
+ * fake "0 consumption" for a day that never was.
  */
 export type CalendarCell =
   | { kind: "day"; date: string; value: number; level: 0 | 1 | 2 | 3 | 4 }
@@ -83,7 +84,10 @@ export type CalendarCell =
  * back to the window's first Monday, tail cells to Sunday — so a
  * trailing-year window ALWAYS lands on a full-year-wide grid, however
  * young the account is. Every cell carries its real calendar date;
- * cells outside [first … today] become gaps (hatched, inert).
+ * cells outside [first … today] become gaps (dimmed; inert without
+ * the tooltip slot — with one they are the popup's engage surface).
+ * The Rust/WASM mirror keeps them inert unconditionally (no popup
+ * runtime in that form).
  *
  * `maxOverride` pins the intensity scale (R2: the component's `max`
  * prop must reach the buckets, not just the data-max attribute — a
@@ -103,17 +107,17 @@ export function calendarGrid(
   const span = total + ((7 - (total % 7)) % 7);
   const max = maxOverride ?? days.reduce((m, d) => Math.max(m, d.value), 0);
   const valueByDate = new Map(days.map((d) => [d.date, d.value]));
-  // A malformed `first` from the future hatches nothing (the clamp
+  // A malformed `first` from the future dims nothing (the clamp
   // keeps the before-check honest).
-  const hatchFrom = first && first <= today ? first : null;
+  const gapFrom = first && first <= today ? first : null;
   const cells: CalendarCell[] = [];
   for (let i = 0; i < span; i++) {
     const date = shiftIso(gridStart, i);
-    // Never hatch a date the server actually shipped: a series whose
+    // Never dim 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:
+    // future gap — the data would vanish behind the dimming. (The
+    // before-first dimming 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.)
@@ -121,7 +125,7 @@ export function calendarGrid(
       cells.push({ kind: "gap", date, phase: "after" });
       continue;
     }
-    if (hatchFrom && date < hatchFrom) {
+    if (gapFrom && date < gapFrom) {
       cells.push({ kind: "gap", date, phase: "before" });
       continue;
     }