hyperweave 0.2.8__tar.gz → 0.2.9__tar.gz

{hyperweave-0.2.8 → hyperweave-0.2.9}/CHANGELOG.md

@@ -5,6 +5,17 @@ All notable changes to HyperWeave are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.9] - 2026-04-21
+
+### Fixed
+
+- **Star history charts now render an authentic growth curve for any repo size.** v0.2.8 fetched only the most-recent 2,000 stargazers for any repo with more than ~2,000 stars, which meant both the 361,000-star `openclaw/openclaw` and the 40,000-star `JuliusBrussee/caveman` rendered as flat horizontal lines near their total-star value — the captured window's variation was invisible on the full-range Y-axis. Star history now uses GraphQL cursor-offset sampling to pull 12 real stargazer timestamps evenly distributed across the repository's full lifetime, regardless of whether the repo has 30 stars or 500,000. The resulting curve shows actual adoption shape — slow-early, explosive-middle, tapering-late — rather than either a hockey-stick or a flat line.
+- **X-axis date labels adapt to the repository's lifetime.** A viral repo that went from 0 to 40K stars in two weeks was being labeled with a single "2026" at the center of its axis; a mature repo with 10 years of history showed the same year-only format. The axis now selects granularity from the actual temporal span — daily labels ("Apr 05", "Apr 12") when the span is under two weeks, weekly under 90 days, month-plus-year under two years, yearly up to ten years, and every-other-year beyond. Labels maintain a minimum 48-pixel horizontal gap so they never collide — the "202324" pileup is gone.
+
+### Changed
+
+- **Parallel GraphQL dispatch is now bounded.** Cold fetches fan out twelve cursor-offset queries across four concurrent in-flight requests via `asyncio.Semaphore`. This keeps cold-fetch latency under ~1 second while staying well below per-minute abuse-detection thresholds that bursty same-token parallelism could otherwise trip.
+
 ## [0.2.8] - 2026-04-20
 
 ### Fixed

{hyperweave-0.2.8 → hyperweave-0.2.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hyperweave
-Version: 0.2.8
+Version: 0.2.9
 Summary: Headless visual output layer for AI agents. One API call → self-contained SVG.
 Project-URL: Repository, https://github.com/InnerAura/hyperweave
 Project-URL: Issues, https://github.com/InnerAura/hyperweave/issues

{hyperweave-0.2.8 → hyperweave-0.2.9}/src/hyperweave/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.2.8'
-__version_tuple__ = version_tuple = (0, 2, 8)
+__version__ = version = '0.2.9'
+__version_tuple__ = version_tuple = (0, 2, 9)
 
 __commit_id__ = commit_id = None

{hyperweave-0.2.8 → hyperweave-0.2.9}/src/hyperweave/connectors/github.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import asyncio
+import base64
 import math
 import re
 from datetime import UTC, datetime
@@ -151,19 +152,25 @@ _STARGAZER_PAGE_SIZE = 100
 _STARGAZER_PAGE_CAP = 400
 _STARGAZER_ACCEPT_HEADER = "application/vnd.github.v3.star+json"
 
-# GraphQL-path constants. Walking backwards from "now" via cursor pagination
-# bypasses the REST 400-page cap entirely. For small repos (≤2000 stars) we
-# get full lifetime coverage; for mega-repos we get a recent-growth window,
-# which is the behavior star-history.com uses for the same reason.
-_GRAPHQL_PAGE_SIZE = 100
-_GRAPHQL_MAX_PAGES = 20  # 20 * 100 = 2000 most-recent stargazers
-
-_STARGAZER_GRAPHQL_QUERY = """
-query StargazerWindow($owner: String!, $repo: String!, $cursor: String) {
+# GraphQL cursor-offset sampling constants.
+#
+# GitHub's GraphQL cursors decode to the literal text ``cursor:<N>`` where
+# N is a 0-indexed offset into the stargazer list. By Base64-encoding
+# ``cursor:<N-1>`` we can construct an ``after:`` anchor that lets ``first: 1``
+# return exactly the Nth stargazer. This bypasses GitHub's 400-page REST cap
+# and lets us sample any offset in a 500K-star repo cheaply.
+#
+# 12 offsets * 1 node per call = 12 GraphQL points per cold fetch.
+# ``asyncio.Semaphore(_GRAPHQL_CONCURRENCY)`` caps fan-out so bursty
+# same-token parallelism doesn't trigger GitHub's per-minute abuse detection.
+_DEFAULT_SAMPLE_COUNT = 12
+_GRAPHQL_CONCURRENCY = 4
+
+_CURSOR_OFFSET_QUERY = """
+query StargazerAtOffset($owner: String!, $repo: String!, $cursor: String) {
   repository(owner: $owner, name: $repo) {
     stargazerCount
-    stargazers(last: 100, before: $cursor) {
-      pageInfo { startCursor hasPreviousPage }
+    stargazers(first: 1, after: $cursor) {
       edges { starredAt }
     }
   }
@@ -171,6 +178,22 @@ query StargazerWindow($owner: String!, $repo: String!, $cursor: String) {
 """
 
 
+def _cursor_for_offset(offset: int) -> str | None:
+    """Return the Base64-encoded cursor for a 1-indexed stargazer position.
+
+    GitHub's GraphQL cursors decode to ``cursor:<N>`` where N is 0-indexed.
+    Constructing them lets us sample any offset within a repo's stargazer
+    list, bypassing both the REST 400-page cap and the cost of walking
+    every page via cursor pagination.
+
+    Returns None for ``offset <= 1`` (no cursor needed — this IS the first
+    entry; passing ``after: None`` to GraphQL starts from the beginning).
+    """
+    if offset <= 1:
+        return None
+    return base64.b64encode(f"cursor:{offset - 1}".encode()).decode()
+
+
 async def fetch_stargazer_history(
     owner: str,
     repo: str,
@@ -199,10 +222,11 @@ async def fetch_stargazer_history(
 
     result: dict[str, Any] | None = None
 
-    # Primary path: GraphQL (requires auth). Walks backwards from most-recent
-    # so mega-repos get a detailed recent-growth curve instead of a hockey
-    # stick. A per-page budget of 20 * 100 = 2000 stargazers per cold fetch
-    # keeps us well under the 5000-points/hour GraphQL rate limit.
+    # Primary path: GraphQL cursor-offset sampling (requires auth). Constructs
+    # cursors for N evenly-distributed stargazer offsets across [1, total_stars]
+    # and fetches one stargazer per offset. Bypasses GitHub's 400-page REST cap,
+    # so a 361K-star repo gets 12 real points across its full lifetime instead
+    # of a hockey-stick or flat line.
     if _get_github_token():
         try:
             result = await _fetch_stargazer_history_graphql(owner, repo, sample_pages)
@@ -221,68 +245,95 @@ async def fetch_stargazer_history(
 async def _fetch_stargazer_history_graphql(
     owner: str,
     repo: str,
-    sample_pages: int,
+    sample_count: int = _DEFAULT_SAMPLE_COUNT,
 ) -> dict[str, Any]:
-    """GraphQL stargazer fetch — walks cursor pagination backwards from most-recent.
-
-    The REST ``/stargazers`` endpoint caps deep pagination at ~400 pages, so
-    for a 361k-star repo we could only ever see stars #1 to #40000 — the
-    early hype window — producing the flat-then-vertical "hockey stick"
-    curve. GraphQL cursor pagination has no such cap; we simply walk backward
-    from the endpoint, collect up to ``_GRAPHQL_MAX_PAGES`` pages, and stop
-    early if we exhaust the repo's history (small repos get full lifetime).
+    """Sample N stargazer timestamps at evenly-distributed cursor offsets.
+
+    Strategy: given a repo's ``total_stars``, fetch one stargazer at each of
+    N evenly-spaced offsets across ``[1, total_stars]``. Each offset maps to
+    a constructed cursor (``base64("cursor:<N-1>")``); GraphQL returns that
+    stargazer's ``starred_at``. Pair with the known offset to form a
+    ``{date, count}`` point. Appends a now-point at ``total_stars``.
+
+    Works for any repo size — 30 stars, 2938 stars, 361k stars — because
+    cursor-offset sampling is not subject to GitHub's 400-page REST cap.
+
+    Concurrency is bounded at ``_GRAPHQL_CONCURRENCY`` to avoid tripping
+    per-minute abuse-detection heuristics on bursty parallel fan-out.
     """
     identifier = f"{owner}/{repo}"
-    variables: dict[str, Any] = {"owner": owner, "repo": repo, "cursor": None}
-
-    all_timestamps: list[str] = []
-    total_stars = 0
-
-    for _ in range(_GRAPHQL_MAX_PAGES):
-        response = await fetch_graphql(_STARGAZER_GRAPHQL_QUERY, variables, provider=PROVIDER)
-        repo_data = (response.get("data") or {}).get("repository")
-        if not repo_data:
-            # Repo doesn't exist or query errored — return empty honestly.
-            return {
-                "points": [],
-                "current_stars": 0,
-                "repo": identifier,
-                "ttl": STARGAZER_HISTORY_TTL,
-            }
-
-        total_stars = int(repo_data.get("stargazerCount", 0))
-        if total_stars == 0:
-            return {
-                "points": [],
-                "current_stars": 0,
-                "repo": identifier,
-                "ttl": STARGAZER_HISTORY_TTL,
-            }
-
-        stargazers = repo_data.get("stargazers") or {}
-        edges = stargazers.get("edges") or []
-        # GraphQL `last/before` returns edges in ASC chronological order.
-        # Prepend so the accumulated list stays sorted oldest→newest across
-        # multiple backward walks.
-        page_timestamps = [e["starredAt"] for e in edges if isinstance(e, dict) and e.get("starredAt")]
-        all_timestamps = page_timestamps + all_timestamps
-
-        page_info = stargazers.get("pageInfo") or {}
-        if not page_info.get("hasPreviousPage"):
-            break
-        variables["cursor"] = page_info.get("startCursor")
 
-    if not all_timestamps:
-        return {
-            "points": [],
-            "current_stars": total_stars,
-            "repo": identifier,
-            "ttl": STARGAZER_HISTORY_TTL,
-        }
+    # First query: learn total_stars and pick up the first stargazer's
+    # timestamp in the same round-trip (offset 1 uses no cursor anyway).
+    first_response = await fetch_graphql(
+        _CURSOR_OFFSET_QUERY,
+        {"owner": owner, "repo": repo, "cursor": None},
+        provider=PROVIDER,
+    )
+    repo_data = (first_response.get("data") or {}).get("repository")
+    if not repo_data:
+        return _empty_stargazer_result(identifier)
+
+    total_stars = int(repo_data.get("stargazerCount", 0))
+    if total_stars == 0:
+        return _empty_stargazer_result(identifier)
 
-    points = _downsample_timestamps(all_timestamps, sample_pages, total_stars)
-    # Append honest "now" point — matches the v0.2.7 §1.4 contract.
-    points.append({"date": datetime.now(UTC).isoformat(), "count": total_stars})
+    first_edges = (repo_data.get("stargazers") or {}).get("edges") or []
+    first_starred_at: str | None = None
+    if first_edges and isinstance(first_edges[0], dict):
+        first_starred_at = first_edges[0].get("starredAt")
+
+    # Clamp sample count to total_stars — small repos get every star sampled
+    # (no point requesting 12 offsets from a 5-star repo).
+    effective_samples = min(sample_count, total_stars)
+
+    # Compute evenly-distributed offsets across the full stargazer list.
+    # Always includes position 1 (oldest) and position total_stars (newest).
+    if effective_samples <= 1:
+        offsets = [1]
+    else:
+        step = (total_stars - 1) / (effective_samples - 1)
+        offsets = sorted({max(1, round(1 + step * i)) for i in range(effective_samples)})
+
+    # Bounded concurrent fan-out: semaphore throttles to _GRAPHQL_CONCURRENCY
+    # in-flight requests at a time. For 12 offsets at concurrency 4, that's
+    # 3 waves of ≤4 calls each → ~1s cold-fetch latency.
+    sem = asyncio.Semaphore(_GRAPHQL_CONCURRENCY)
+
+    async def _fetch_one(offset: int) -> tuple[int, str | None]:
+        # Offset 1 is already in hand from the total_stars lookup.
+        if offset == 1 and first_starred_at is not None:
+            return offset, first_starred_at
+        cursor = _cursor_for_offset(offset)
+        async with sem:
+            resp = await fetch_graphql(
+                _CURSOR_OFFSET_QUERY,
+                {"owner": owner, "repo": repo, "cursor": cursor},
+                provider=PROVIDER,
+            )
+        edges_data = (((resp.get("data") or {}).get("repository") or {}).get("stargazers") or {}).get("edges") or []
+        starred_at: str | None = None
+        if edges_data and isinstance(edges_data[0], dict):
+            starred_at = edges_data[0].get("starredAt")
+        return offset, starred_at
+
+    results = await asyncio.gather(
+        *[_fetch_one(off) for off in offsets],
+        return_exceptions=True,
+    )
+
+    points: list[dict[str, Any]] = []
+    for item in results:
+        if isinstance(item, BaseException):
+            continue
+        offset, starred_at = item
+        if starred_at is None:
+            continue
+        points.append({"date": starred_at, "count": offset})
+
+    # Append the honest now-point: current timestamp at the real total count.
+    if points:
+        points.append({"date": datetime.now(UTC).isoformat(), "count": total_stars})
     points.sort(key=lambda p: p["date"])
 
     return {
@@ -293,33 +344,14 @@ async def _fetch_stargazer_history_graphql(
     }
 
 
-def _downsample_timestamps(
-    timestamps: list[str],
-    n_samples: int,
-    total_stars: int,
-) -> list[dict[str, Any]]:
-    """Reduce N ascending timestamps to ``n_samples`` evenly-spaced points.
-
-    The count at each sampled timestamp is computed backwards from
-    ``total_stars``: since ``timestamps`` represents the most-recent
-    ``len(timestamps)`` stargazers in chronological order, the final
-    timestamp corresponds to ``total_stars`` and the earliest to
-    ``total_stars - (n - 1)``.
-    """
-    n = len(timestamps)
-    if n == 0:
-        return []
-    base = total_stars - (n - 1)
-    if n <= n_samples:
-        return [{"date": ts, "count": base + idx} for idx, ts in enumerate(timestamps)]
-
-    # Pick n_samples evenly-spaced indices across [0, n-1], always including
-    # the endpoints so the curve starts and ends at the captured extremes.
-    if n_samples <= 1:
-        return [{"date": timestamps[-1], "count": total_stars}]
-    step = (n - 1) / (n_samples - 1)
-    indices = sorted({round(i * step) for i in range(n_samples)})
-    return [{"date": timestamps[idx], "count": base + idx} for idx in indices]
+def _empty_stargazer_result(identifier: str) -> dict[str, Any]:
+    """Shared empty-state shape for zero-star or missing-repo cases."""
+    return {
+        "points": [],
+        "current_stars": 0,
+        "repo": identifier,
+        "ttl": STARGAZER_HISTORY_TTL,
+    }
 
 
 async def _fetch_stargazer_history_rest(

{hyperweave-0.2.8 → hyperweave-0.2.9}/src/hyperweave/render/chart_engine.py

@@ -32,7 +32,7 @@ from __future__ import annotations
 
 import math
 from dataclasses import dataclass
-from datetime import UTC, datetime
+from datetime import UTC, datetime, timedelta
 from typing import Any
 
 # ── Data types ─────────────────────────────────────────────────────────────
@@ -513,35 +513,95 @@ def _build_y_labels(ticks: list[int], v_min: int, v_max: int, vp: Viewport) -> l
     return out
 
 
-def _build_x_year_labels(points: list[ChartPoint], vp: Viewport) -> list[dict[str, Any]]:
-    """Return year-string labels positioned at jan-1 boundaries in the data range.
+# Minimum horizontal pixel gap between two x-axis labels. Year labels (4 chars)
+# need a bit more room than milestone labels (40 px); 48 px keeps well-spaced
+# "2023" / "2024" / "2025" readable without forcing unnecessary drops.
+_X_LABEL_MIN_GAP_PX: int = 48
 
-    Matches star-history.com's convention: just year numbers (2024, 2025, 2026)
-    at the X positions where each year begins. No "EARLY '24", "MID '25", etc.
 
-    Single-year spans collapse to one label at the viewport center.
+def _build_x_date_labels(points: list[ChartPoint], vp: Viewport) -> list[dict[str, Any]]:
+    """Adaptive x-axis date labels — granularity follows the data's temporal span.
+
+    Tick formats:
+        < 14 days  → daily   ("Apr 05")
+        < 90 days  → weekly  ("Apr 05" at 7-day steps)
+        < 2 years  → monthly ("Apr 2026")
+        < 10 years → yearly  ("2026")
+        else       → every other year ("2012", "2014", ...)
+
+    A single-point input renders one centered label with full "%b %d, %Y".
+    After candidate generation, a min-gap de-overlap pass removes any middle
+    label within ``_X_LABEL_MIN_GAP_PX`` of a previously-kept one. The first
+    and last labels are preserved unconditionally because they're the
+    temporal endpoints a reader expects to see.
     """
     if not points:
         return []
-    y_start = points[0].date.year
-    y_end = points[-1].date.year
-    if len(points) == 1 or y_start == y_end:
-        return [{"x": vp.x + vp.w // 2, "text": str(y_start), "anchor": "middle"}]
-
-    t0 = points[0].date.timestamp()
-    t1 = points[-1].date.timestamp()
-    t_span = max(1.0, t1 - t0)
-
-    labels: list[dict[str, Any]] = [{"x": vp.x, "text": str(y_start), "anchor": "start"}]
-    for y in range(y_start + 1, y_end + 1):
-        jan1 = datetime(y, 1, 1, tzinfo=UTC).timestamp()
-        if t0 < jan1 <= t1:
-            frac = (jan1 - t0) / t_span
-            px = vp.x + round(frac * vp.w)
-            # Anchor at right-edge if within 20px of viewport right; else middle.
-            anchor = "end" if (vp.x + vp.w) - px < 20 else "middle"
-            labels.append({"x": px, "text": str(y), "anchor": anchor})
-    return labels
+    if len(points) == 1:
+        p = points[0]
+        return [{"x": vp.x + vp.w // 2, "text": p.date.strftime("%b %d, %Y"), "anchor": "middle"}]
+
+    t0 = points[0].date
+    t1 = points[-1].date
+    span = t1 - t0
+
+    # Select granularity + format from the actual span.
+    if span < timedelta(days=14):
+        format_str = "%b %d"
+        step = timedelta(days=1)
+    elif span < timedelta(days=90):
+        format_str = "%b %d"
+        step = timedelta(days=7)
+    elif span < timedelta(days=730):
+        format_str = "%b %Y"
+        step = timedelta(days=30)  # ≈ 1 month
+    elif span < timedelta(days=3650):
+        format_str = "%Y"
+        step = timedelta(days=365)
+    else:
+        format_str = "%Y"
+        step = timedelta(days=730)  # every other year
+
+    # Generate candidate ticks, projecting each to pixel x via the same scale
+    # as the polyline so labels sit directly under their corresponding data.
+    t_span_s = max(span.total_seconds(), 1.0)
+    candidates: list[dict[str, Any]] = []
+    cursor = t0
+    while cursor <= t1:
+        frac_t = (cursor - t0).total_seconds() / t_span_s
+        px = vp.x + round(frac_t * vp.w)
+        candidates.append({"x": px, "text": cursor.strftime(format_str), "anchor": "middle"})
+        cursor = cursor + step
+
+    # Ensure the terminal endpoint is in the candidate set (may not land on a
+    # step boundary otherwise).
+    last_px = vp.x + vp.w
+    if not candidates or candidates[-1]["x"] < last_px - 2:
+        candidates.append({"x": last_px, "text": t1.strftime(format_str), "anchor": "end"})
+
+    # First label flush with the y-axis for a cleaner left edge.
+    candidates[0]["anchor"] = "start"
+
+    # De-overlap: preserve first + last; drop any middle label within min-gap
+    # of a previously-kept one. Same algorithm as _build_milestones.
+    if len(candidates) <= 2:
+        return candidates
+    kept: list[dict[str, Any]] = [candidates[0]]
+    for label in candidates[1:-1]:
+        if label["x"] - kept[-1]["x"] >= _X_LABEL_MIN_GAP_PX:
+            kept.append(label)
+    # The terminal endpoint is always included. If it's too close to the
+    # last-kept middle label, or has identical text (e.g. yearly granularity
+    # where the last jan-1 tick and the terminal point both read "2026"),
+    # replace that middle label with the terminal rather than duplicating.
+    last_candidate = candidates[-1]
+    too_close = last_candidate["x"] - kept[-1]["x"] < _X_LABEL_MIN_GAP_PX
+    same_text = last_candidate["text"] == kept[-1]["text"]
+    if too_close or same_text:
+        kept[-1] = last_candidate
+    else:
+        kept.append(last_candidate)
+    return kept
 
 
 def _build_empty_state(vp: Viewport, message: str) -> dict[str, Any] | None:
@@ -611,7 +671,7 @@ def build_chart_svg(
         ticks = _nice_y_ticks(v_max)
         effective_max = ticks[-1] if ticks else max(v_max, 1)
         y_labels = _build_y_labels(ticks, 0, effective_max, viewport)
-        x_labels = _build_x_year_labels(points, viewport)
+        x_labels = _build_x_date_labels(points, viewport)
         # Project with zero-baseline so the polyline aligns to the tick labels.
         projected = _project_points(points, viewport, v_min=0, v_max=effective_max)
     else:

{hyperweave-0.2.8 → hyperweave-0.2.9}/tests/test_chart_engine.py

@@ -19,7 +19,7 @@ from hyperweave.render.chart_engine import (
     _build_markers,
     _build_milestones,
     _build_polyline_points,
-    _build_x_year_labels,
+    _build_x_date_labels,
     _format_y_tick,
     _nice_y_ticks,
     _normalize_points,
@@ -457,8 +457,8 @@ def test_format_y_tick_integer_and_k_notation() -> None:
 # ── X-axis year labels ────────────────────────────────────────────────
 
 
-def test_x_year_labels_single_year(sample_viewport: Viewport) -> None:
-    """Data entirely within one year → one label centered on the viewport."""
+def test_x_date_labels_monthly_granularity_for_year_one_span(sample_viewport: Viewport) -> None:
+    """Data spanning ~10 months → monthly format ("Mon Year"), not yearly."""
     pts = _normalize_points(
         [
             {"date": "2025-01-15", "count": 1},
@@ -466,18 +466,85 @@ def test_x_year_labels_single_year(sample_viewport: Viewport) -> None:
             {"date": "2025-11-20", "count": 6},
         ]
     )
-    labels = _build_x_year_labels(pts, sample_viewport)
-    assert labels == [
-        {
-            "x": sample_viewport.x + sample_viewport.w // 2,
-            "text": "2025",
-            "anchor": "middle",
-        }
-    ]
+    labels = _build_x_date_labels(pts, sample_viewport)
+    # All labels should use "Mon YYYY" format (e.g., "Jan 2025", "Apr 2025").
+    assert labels, "expected at least one label for a 10-month span"
+    for label in labels:
+        # Match "Abc 2025" pattern — three-letter month followed by space + year.
+        parts = label["text"].split()
+        assert len(parts) == 2
+        assert parts[1] == "2025"
+
+
+def test_x_date_labels_yearly_for_multi_year_range(sample_viewport: Viewport) -> None:
+    """Three-year span → yearly format (2024, 2025, 2026)."""
+    pts = _normalize_points(
+        [
+            {"date": "2024-01-01", "count": 1},
+            {"date": "2025-06-01", "count": 100},
+            {"date": "2026-04-01", "count": 500},
+        ]
+    )
+    labels = _build_x_date_labels(pts, sample_viewport)
+    texts = [label["text"] for label in labels]
+    # Every label is a 4-digit year.
+    for text in texts:
+        assert text.isdigit() and len(text) == 4
+    # First and last are the endpoints of the data.
+    assert labels[0]["anchor"] == "start"
+    assert labels[0]["x"] == sample_viewport.x
+    # Data starts in 2024 and ends in 2026; endpoints must reflect that.
+    assert texts[0] == "2024"
+    assert texts[-1] == "2026"
+
+
+def test_x_date_labels_daily_for_viral_two_week_span(sample_viewport: Viewport) -> None:
+    """2-week span (caveman case) → daily format ("Apr 05", "Apr 12"...).
+
+    This is the regression test that locks in the fix for the
+    JuliusBrussee/caveman rendering — the old year-only labels showed a
+    single lonely "2026" mid-axis; daily granularity makes the 2-week
+    adoption curve legible.
+    """
+    pts = _normalize_points(
+        [
+            {"date": "2026-04-05T00:00:00Z", "count": 1},
+            {"date": "2026-04-10T00:00:00Z", "count": 15_000},
+            {"date": "2026-04-19T00:00:00Z", "count": 40_000},
+        ]
+    )
+    labels = _build_x_date_labels(pts, sample_viewport)
+    # Every label uses "Mon DD" format — no year suffix, no single "2026".
+    for label in labels:
+        parts = label["text"].split()
+        assert len(parts) == 2, f"expected 'Mon DD' format, got {label['text']!r}"
+        # Day portion is zero-padded 2-digit integer.
+        assert parts[1].isdigit() and len(parts[1]) == 2
 
 
-def test_x_year_labels_multi_year_range(sample_viewport: Viewport) -> None:
-    """Three-year span → start year at left, interior years at jan-1 positions."""
+def test_x_date_labels_every_other_year_for_ancient_repo(sample_viewport: Viewport) -> None:
+    """Repo spanning >10 years → every-other-year ticks to keep the axis readable."""
+    pts = _normalize_points(
+        [
+            {"date": "2010-06-01", "count": 1},
+            {"date": "2026-06-01", "count": 500_000},
+        ]
+    )
+    labels = _build_x_date_labels(pts, sample_viewport)
+    texts = [label["text"] for label in labels]
+    # Endpoints always preserved.
+    assert texts[0] == "2010"
+    # Endpoint is dropped/merged into the last-kept if too close; 2026 should be present.
+    assert "2026" in texts
+
+
+def test_x_date_labels_deoverlap_drops_clustered_middles(sample_viewport: Viewport) -> None:
+    """De-overlap pass: temporally-close middle labels are dropped; endpoints preserved.
+
+    With a narrow viewport (just 80px wide) and a 3-year span, the yearly
+    labels at jan-1 boundaries would collide. Only endpoints survive.
+    """
+    narrow_vp = Viewport(x=0, y=0, w=80, h=50)
     pts = _normalize_points(
         [
             {"date": "2024-01-01", "count": 1},
@@ -485,19 +552,42 @@ def test_x_year_labels_multi_year_range(sample_viewport: Viewport) -> None:
             {"date": "2026-04-01", "count": 500},
         ]
     )
-    labels = _build_x_year_labels(pts, sample_viewport)
+    labels = _build_x_date_labels(pts, narrow_vp)
+    # Under severe width pressure, only the endpoints survive.
+    assert len(labels) <= 2
     texts = [label["text"] for label in labels]
-    # Expect every year in the range represented exactly once.
-    assert texts == ["2024", "2025", "2026"]
-    # Start year anchored at left, subsequent labels middle/end.
+    assert "2024" in texts
+    assert "2026" in texts
+
+
+def test_x_date_labels_preserve_endpoints_unconditionally(sample_viewport: Viewport) -> None:
+    """Even when middle labels are dropped, first and last labels persist."""
+    pts = _normalize_points(
+        [
+            {"date": "2024-01-01", "count": 1},
+            {"date": "2026-04-01", "count": 500},
+        ]
+    )
+    labels = _build_x_date_labels(pts, sample_viewport)
+    # Two-point input with wide viewport keeps both endpoints.
+    assert len(labels) >= 2
     assert labels[0]["anchor"] == "start"
-    assert labels[0]["x"] == sample_viewport.x
+    assert labels[-1]["anchor"] == "end"
+
+
+def test_x_date_labels_single_point_full_date(sample_viewport: Viewport) -> None:
+    """Single data point → one centered full-date label ("Apr 05, 2026")."""
+    pts = _normalize_points([{"date": "2026-04-05", "count": 1}])
+    labels = _build_x_date_labels(pts, sample_viewport)
+    assert len(labels) == 1
+    assert labels[0]["text"] == "Apr 05, 2026"
+    assert labels[0]["anchor"] == "middle"
 
 
-def test_x_year_labels_empty_points() -> None:
+def test_x_date_labels_empty_points() -> None:
     """No points → no labels (caller should render an empty-state overlay instead)."""
     vp = Viewport(x=0, y=0, w=100, h=50)
-    assert _build_x_year_labels([], vp) == []
+    assert _build_x_date_labels([], vp) == []
 
 
 # ── Zero-time-span defense (bug 2 reproducer) ────────────────────────