cctally 1.5.0 → 1.6.0

package/bin/cctally

@@ -27638,6 +27638,33 @@ def _share_now_utc() -> dt.datetime:
     return dt.datetime.now(dt.timezone.utc)
 
 
+def _share_now_utc_iso() -> str:
+    """`generated_at` ISO-8601 source for /api/share/render snapshot envelopes.
+
+    Honors `CCTALLY_AS_OF` like `_share_now_utc` so fixture goldens stay
+    deterministic across the CLI and HTTP paths. Format `YYYY-MM-DDTHH:MM:SSZ`.
+    """
+    return _share_now_utc().strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+# Spec §11.4 — recent-shares ring buffer caps at 20. Server-side trim
+# in `_handle_share_history_post` so the on-disk `config.json` can't
+# grow unbounded even if a misbehaving client floods POSTs.
+_SHARE_HISTORY_RING_CAP = 20
+
+
+def _share_history_recipe_id() -> str:
+    """Server-stamped opaque id for a history record.
+
+    Random base16 (26 chars / 13 bytes) is sufficient: we order by
+    insertion (ring buffer position), never by id, so we don't need
+    ULID timestamp-prefix monotonicity. `secrets.token_hex` keeps us
+    on stdlib and avoids the predictability of `random`.
+    """
+    import secrets
+    return secrets.token_hex(13)
+
+
 def _share_resolve_version() -> str:
     """Source from CHANGELOG via the existing release helper. Empty string if unset.
 
@@ -28916,6 +28943,851 @@ def _build_session_snapshot(
     )
 
 
+# ---- v2 share panel_data builders (spec §5.2, plan M1.6) -------------
+#
+# These translate the live dashboard `DataSnapshot` into the dict shapes
+# the M1.4 Recap builders (in `bin/_lib_share_templates.py`) consume.
+# They're a thin extract step — the DataSnapshot was already built by
+# the sync thread, so this path doesn't re-query the DB on the share
+# hot path.
+#
+# Per-panel shape contracts live in each Recap builder's docstring in
+# `bin/_lib_share_templates.py` (see `_build_<panel>_recap`); the keys
+# below MUST stay in lockstep with those docstrings — the
+# producer/consumer contract.
+#
+# When the snapshot has no data for a given panel (fresh install, no
+# sync yet), the builder returns a minimal empty-shaped dict that the
+# downstream Recap builder renders as a "no data" snapshot (kernel
+# handles empty `weeks=[]` / `days=[]` / etc.).
+
+
+def _share_iso(value) -> "str | None":
+    """Coerce a datetime / ISO-string into an ISO-8601 string with `Z` suffix.
+
+    DataSnapshot mixes attribute types (`week_start_at` is a
+    `dt.datetime`; `WeeklyPeriodRow.week_start_at` is already a string).
+    Recap builders' `_parse_iso_utc` accepts both shapes via fromisoformat
+    + `Z`-swap, but normalizing here keeps the wire format consistent.
+    """
+    if value is None:
+        return None
+    if isinstance(value, dt.datetime):
+        v = value if value.tzinfo else value.replace(tzinfo=dt.timezone.utc)
+        return v.astimezone(dt.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+    return str(value)
+
+
+# ---- Period override (spec §6.2 Q4 + Codex P2 on PR #35) ----
+#
+# The share modal's Period control offers three kinds — current, previous,
+# custom — but the original render path consumed the dashboard's cached
+# DataSnapshot directly, which only ever holds "current" data. Override
+# semantics by panel:
+#
+#   panel        current             previous              custom (start/end)
+#   --------     ------------------  --------------------  -------------------
+#   weekly       this subscription   one week earlier      week containing end
+#                week
+#   daily        last 7 display-tz   7 days earlier        7 days ending at end
+#                days ending today
+#   monthly      last 12 months      12 months earlier     12 months ending at end
+#                ending now
+#   trend        last 8 weeks        8 weeks earlier       8 weeks ending at end
+#                ending now
+#   blocks       recent 5h blocks    blocks ending one     blocks ending at end
+#                                     5h-window earlier
+#   forecast     future projection   (rejected: previous
+#                from now             forecast doesn't exist)
+#   current-week this subscription   (rejected: panel IS current)
+#                week
+#   sessions     recent sessions     (deferred: ambiguous semantics — could
+#                                     mean "older sessions" or "sessions in
+#                                     date range"; revisit when use case clear)
+#
+# Override mechanics: derive a `now_utc` from the period option and
+# re-build only the relevant DataSnapshot field by calling the same
+# `_dashboard_build_*` function the sync thread uses, just with a
+# shifted `now_utc`. `dataclasses.replace` returns a new DataSnapshot
+# with that field swapped; everything downstream (panel_data builder,
+# template builder, kernel render) consumes it unchanged.
+#
+# Validation failures land on the request as HTTP 400 with
+# `field: "options.period.<key>"` so the UI can highlight the offending
+# control.
+
+_SHARE_PANELS_PERIOD_FIXED = ("forecast", "current-week", "sessions")
+# Panels whose period is intrinsic to the panel's identity. We accept
+# `kind="current"` (= no override) and reject anything else with 400.
+
+_SHARE_PANELS_PERIOD_OVERRIDABLE = ("weekly", "daily", "monthly", "trend", "blocks")
+
+
+def _share_resolve_period(panel: str, options: dict):
+    """Return (now_utc_override, start_override, error_dict) for the period.
+
+    - `(None, None, None)` — no override needed (period absent or
+      `kind="current"`). Caller continues with the cached DataSnapshot.
+    - `(datetime, None, None)` — `kind="previous"`. Caller rebuilds with
+      this `now_utc`; window length stays at the panel default.
+    - `(datetime, datetime, None)` — `kind="custom"`. Caller rebuilds
+      with `now_utc = end_dt` AND a derived window length spanning
+      `[start_dt, end_dt]` (computed by `_share_apply_period_override`
+      per panel). Spec §6.3 advertises "Custom (start–end pickers)";
+      honoring the start picker means the rendered window's left edge
+      moves with it. The 2-tuple form silently ignored `start_dt`.
+    - `(None, None, {...})` — validation failure; caller emits 400.
+
+    `parse_iso_datetime` (the same parser used by every other share
+    surface) accepts trailing `Z` / `+HH:MM` and naive forms. Naive
+    inputs are treated as UTC by `parse_iso_datetime` and downstream
+    UTC-fixup, so a date-only string like ``"2026-05-04"`` lands at
+    midnight UTC.
+    """
+    period = options.get("period")
+    if period is None or not isinstance(period, dict):
+        # Absent → no override, defaults to current. (Permissive: the
+        # UI always sends a period block, but older basket recipes /
+        # CLI parity may omit it.)
+        return (None, None, None)
+    kind = period.get("kind", "current")
+    if kind not in ("current", "previous", "custom"):
+        return (None, None, {"error": f"unknown period kind: {kind!r}",
+                              "field": "options.period.kind"})
+    if panel in _SHARE_PANELS_PERIOD_FIXED:
+        if kind != "current":
+            return (None, None, {
+                "error": (f"panel {panel!r} only supports period kind='current'; "
+                          f"got {kind!r}"),
+                "field": "options.period.kind",
+            })
+        return (None, None, None)
+    # Overridable panels — handle each kind.
+    if kind == "current":
+        return (None, None, None)
+    if kind == "previous":
+        delta = _share_previous_period_delta(panel)
+        return (_share_now_utc() - delta, None, None)
+    # kind == "custom"
+    start_str = period.get("start")
+    end_str = period.get("end")
+    if not isinstance(start_str, str) or not start_str \
+            or not isinstance(end_str, str) or not end_str:
+        return (None, None, {
+            "error": "custom period requires non-empty start + end ISO dates",
+            "field": "options.period",
+        })
+    try:
+        start_dt = parse_iso_datetime(start_str, "options.period.start")
+        end_dt = parse_iso_datetime(end_str, "options.period.end")
+    except ValueError as exc:
+        return (None, None, {"error": f"invalid period date: {exc}",
+                              "field": "options.period"})
+    if end_dt <= start_dt:
+        return (None, None, {
+            "error": ("custom period end must be strictly after start "
+                      f"(got start={start_str!r}, end={end_str!r})"),
+            "field": "options.period",
+        })
+    return (end_dt, start_dt, None)
+
+
+def _share_custom_window_n(panel: str, start_dt: "dt.datetime",
+                            end_dt: "dt.datetime") -> int:
+    """Per-panel window length covering `[start_dt, end_dt]`, min 1.
+
+    Each overridable panel exposes a different unit:
+        - weekly / trend → weeks
+        - daily          → days (inclusive)
+        - monthly        → calendar months (inclusive)
+    Blocks doesn't use this helper — its builder is window-anchored via
+    `week_start_at`/`week_end_at`, not `n`, so we pass `start_dt`/`end_dt`
+    directly to `_dashboard_build_blocks_panel`.
+
+    Inputs are timezone-aware UTC datetimes (`parse_iso_datetime` UTCs
+    naive inputs upstream). Math is purely on the timedelta + calendar
+    diffs; `_dashboard_build_monthly_periods` does its own display-tz
+    bucketing on the resulting window.
+    """
+    import math as _math
+    delta_seconds = (end_dt - start_dt).total_seconds()
+    delta_days = _math.ceil(delta_seconds / 86400.0)
+    if panel in ("weekly", "trend"):
+        return max(1, _math.ceil(delta_days / 7))
+    if panel == "daily":
+        return max(1, int(delta_days))
+    if panel == "monthly":
+        months = ((end_dt.year - start_dt.year) * 12
+                  + (end_dt.month - start_dt.month) + 1)
+        return max(1, months)
+    # Shouldn't reach here — `_share_apply_period_override` handles
+    # blocks separately. Defensive: return 1 rather than raising.
+    return 1
+
+
+def _share_previous_period_delta(panel: str) -> "dt.timedelta":
+    """How far back `now_utc` shifts for `kind='previous'` on each panel.
+
+    weekly/daily: 7 days. monthly: one whole month worth (we shift to
+    the last day of the previous month at call time to handle variable
+    month length, so this is unused — the caller routes through
+    `_share_resolve_period` which special-cases monthly). trend: 8 weeks
+    (one trend window). blocks: 5 hours (one block).
+    """
+    if panel == "weekly":
+        return dt.timedelta(days=7)
+    if panel == "daily":
+        return dt.timedelta(days=7)
+    if panel == "monthly":
+        return dt.timedelta(days=30)  # close-enough for the resolver;
+                                       # see _share_resolve_period_monthly
+                                       # below for the calendar-aware
+                                       # version when needed.
+    if panel == "trend":
+        return dt.timedelta(days=8 * 7)
+    if panel == "blocks":
+        return dt.timedelta(hours=5)
+    raise ValueError(f"_share_previous_period_delta: no delta for panel {panel!r}")
+
+
+def _share_apply_period_override(panel: str, options: dict,
+                                  snap: "DataSnapshot | None"):
+    """Return (snap_or_None, error_dict_or_None).
+
+    Walks `_share_resolve_period`, then re-builds the panel's DataSnapshot
+    field from DB when an override is requested. `dataclasses.replace`
+    yields a shallow copy with one field swapped. Returns the original
+    `snap` unchanged when no override applies.
+    """
+    if snap is None:
+        # No cached snapshot to override against — return None unchanged
+        # and let the panel_data builder's empty-snapshot path handle it.
+        # Still validate the period option so the user gets a 400 on
+        # malformed input even before the sync thread's first tick.
+        _, _, err = _share_resolve_period(panel, options)
+        return (snap, err)
+    now_override, start_override, err = _share_resolve_period(panel, options)
+    if err is not None:
+        return (None, err)
+    if now_override is None:
+        return (snap, None)
+    # For `kind="custom"`, derive a per-panel window length covering
+    # `[start_override, now_override]` so the rendered window honors the
+    # Start picker (spec §6.3). For `kind="previous"`, `start_override`
+    # is None → window length stays at the panel's default.
+    n_override = (
+        _share_custom_window_n(panel, start_override, now_override)
+        if start_override is not None else None
+    )
+    import dataclasses as _dc
+    conn = open_db()
+    try:
+        if panel == "weekly":
+            kwargs: dict = {"skip_sync": True}
+            if n_override is not None:
+                kwargs["n"] = n_override
+            rows = _dashboard_build_weekly_periods(conn, now_override, **kwargs)
+            return (_dc.replace(snap, weekly_periods=rows), None)
+        if panel == "daily":
+            display_tz_name = options.get("display_tz", "Etc/UTC")
+            try:
+                display_tz = ZoneInfo(display_tz_name) if display_tz_name else None
+            except Exception:
+                display_tz = None
+            kwargs = {"skip_sync": True, "display_tz": display_tz}
+            if n_override is not None:
+                kwargs["n"] = n_override
+            rows = _dashboard_build_daily_panel(conn, now_override, **kwargs)
+            return (_dc.replace(snap, daily_panel=rows), None)
+        if panel == "monthly":
+            kwargs = {"skip_sync": True}
+            if n_override is not None:
+                kwargs["n"] = n_override
+            rows = _dashboard_build_monthly_periods(conn, now_override, **kwargs)
+            return (_dc.replace(snap, monthly_periods=rows), None)
+        if panel == "trend":
+            kwargs = {"skip_sync": True}
+            if n_override is not None:
+                kwargs["count"] = n_override
+            rows = _tui_build_trend(conn, now_override, **kwargs)
+            return (_dc.replace(snap, trend=rows), None)
+        if panel == "blocks":
+            # `_dashboard_build_blocks_panel` is window-anchored via
+            # `week_start_at`/`week_end_at`, not `n`. For `kind='custom'`,
+            # use the user's [start_dt, end_dt] verbatim. For
+            # `kind='previous'`, fall back to a 7-day window ending at
+            # the override `now_utc` (the spec's prior-block semantics —
+            # intentionally NOT aligned to subscription-week boundaries
+            # since the share period override is wall-clock-aware, not
+            # quota-aware).
+            if start_override is not None:
+                week_start_at = start_override
+                week_end_at = now_override
+            else:
+                week_start_at = now_override - dt.timedelta(days=7)
+                week_end_at = now_override
+            rows = _dashboard_build_blocks_panel(
+                conn, now_override,
+                week_start_at=week_start_at,
+                week_end_at=week_end_at,
+                skip_sync=True,
+            )
+            return (_dc.replace(snap, blocks_panel=rows), None)
+        # forecast / current-week / sessions: resolver already gated; we
+        # only reach here for `kind="current"`, which returns no
+        # override.
+        return (snap, None)
+    finally:
+        conn.close()
+
+
+def _share_apply_content_toggles(snap_built, options: dict):
+    """Strip chart / table from a built ShareSnapshot per render options.
+
+    The render kernel consumes whatever the template builder emits, so
+    chart/table on-off can't be expressed by the builder alone (every
+    builder unconditionally emits both). Apply the toggle here, after
+    the builder, before `_scrub` and `render`. ShareSnapshot is frozen;
+    `dataclasses.replace` returns a new instance.
+
+    Defaults preserve pre-toggle behavior: `show_chart` defaults to
+    True, `show_table` defaults to True. Explicit False on either
+    drops the corresponding payload.
+    """
+    import dataclasses as _dc
+    show_chart = bool(options.get("show_chart", True))
+    show_table = bool(options.get("show_table", True))
+    changes: dict = {}
+    if not show_chart:
+        changes["chart"] = None
+    if not show_table:
+        changes["columns"] = ()
+        changes["rows"] = ()
+    if not changes:
+        return snap_built
+    return _dc.replace(snap_built, **changes)
+
+
+# Cap on how many `(project, cost)` rows builders return for top_projects.
+# Templates take `top_n` from options (default 5, see _lib_share_templates)
+# and apply their own cap on top of this. The headroom matters because:
+#   (a) the scrubber walks ProjectCells once per row, so unbounded length
+#       balloons render-time anonymization cost;
+#   (b) the live preview iframe streams the full table chrome;
+#   (c) 20 covers any realistic `top_n` knob value (UI typically caps at 10).
+_SHARE_TOP_PROJECTS_BUILDER_CAP = 20
+
+
+def _share_top_projects_for_range(
+    range_start: "dt.datetime",
+    range_end: "dt.datetime",
+    *,
+    skip_sync: bool = True,
+) -> list[tuple[str, float]]:
+    """Aggregate session_entries in `[range_start, range_end]` by project_path.
+
+    Returns `[(project_path_or_'(unknown)', cost_usd), ...]` sorted desc by
+    cost and capped at `_SHARE_TOP_PROJECTS_BUILDER_CAP`. Templates apply
+    a further `top_n` cap (default 5).
+
+    Routes through `get_claude_session_entries` so we get `project_path`
+    in the join — same cache-first/lock-contention/direct-JSONL fallback
+    chain the rest of the share path relies on. `skip_sync=True` by
+    default: the sync thread has already done its tick at snapshot-build
+    time, and a per-request ingest would block the share render on
+    `cache.db.lock`.
+
+    Cost computation goes through `_calculate_entry_cost` — the
+    single-source-of-truth pricing path. Mirrors `_compute_block_totals`'
+    `by_project` bucketing exactly, so the reconcile invariant
+    `SUM(top_projects) ≈ panel.cost_usd` is preserved within ULP drift
+    when the panel's cost matches the same time range (e.g., current
+    week, current 5h block).
+
+    NULL `project_path` collapses to the `(unknown)` sentinel. Anon
+    happens later in `_scrub()`; builders always emit real names per
+    the kernel's privacy chokepoint contract.
+    """
+    bucket: dict[str, float] = {}
+    try:
+        entries = get_claude_session_entries(
+            range_start, range_end, skip_sync=skip_sync,
+        )
+    except Exception:
+        # `get_claude_session_entries` already has its own fallback chain,
+        # but if even that fails (e.g., HOME unset in a fixture run with
+        # no monkeypatch), don't break the whole share render — just emit
+        # an empty top_projects.
+        return []
+    for entry in entries:
+        usage = {
+            "input_tokens":                entry.input_tokens,
+            "output_tokens":               entry.output_tokens,
+            "cache_creation_input_tokens": entry.cache_creation_tokens,
+            "cache_read_input_tokens":     entry.cache_read_tokens,
+        }
+        cost = _calculate_entry_cost(
+            entry.model, usage, mode="auto", cost_usd=entry.cost_usd,
+        )
+        key = entry.project_path or "(unknown)"
+        bucket[key] = bucket.get(key, 0.0) + cost
+    ranked = sorted(bucket.items(), key=lambda kv: -kv[1])
+    return [(path, cost) for path, cost in ranked[:_SHARE_TOP_PROJECTS_BUILDER_CAP]]
+
+
+def _build_share_panel_data(panel: str, options: dict,
+                            snap: "DataSnapshot | None") -> dict:
+    """Dispatch to the per-panel builder; reuses the dashboard DataSnapshot.
+
+    Each per-panel builder reads from the already-built `DataSnapshot`
+    rather than re-running CLI aggregation queries — keeps /api/share/render
+    cheap and ensures the share artifact matches what the dashboard panel
+    is currently showing.
+    """
+    if panel == "weekly":      return _build_weekly_share_panel_data(options, snap)
+    if panel == "daily":       return _build_daily_share_panel_data(options, snap)
+    if panel == "monthly":     return _build_monthly_share_panel_data(options, snap)
+    if panel == "trend":       return _build_trend_share_panel_data(options, snap)
+    if panel == "forecast":    return _build_forecast_share_panel_data(options, snap)
+    if panel == "blocks":      return _build_blocks_share_panel_data(options, snap)
+    if panel == "sessions":    return _build_sessions_share_panel_data(options, snap)
+    if panel == "current-week": return _build_current_week_share_panel_data(options, snap)
+    raise ValueError(f"unknown share panel: {panel!r}")
+
+
+def _share_empty_week_stub() -> dict:
+    """Minimal week shape so empty snapshots render as "no data" cleanly.
+
+    Recap builders index `weeks[idx]` directly; supplying one zero-filled
+    row keeps that access safe without leaking misleading numbers (the
+    rendered artifact shows $0.00 / 0.0% — accurate for an empty install).
+    """
+    return {
+        "start_date":     _share_now_utc().strftime("%Y-%m-%d"),
+        "cost_usd":       0.0,
+        "pct_used":       0.0,
+        "dollar_per_pct": 0.0,
+        "top_projects":   [],
+    }
+
+
+def _build_weekly_share_panel_data(options: dict,
+                                    snap: "DataSnapshot | None") -> dict:
+    """Weekly panel_data — last 8 subscription weeks + current-week index.
+
+    Reuses `DataSnapshot.weekly_periods` (WeeklyPeriodRow list), already
+    built by `_dashboard_build_weekly_periods` in the sync thread. Empty
+    snapshots emit a one-week stub so the Recap builder's `weeks[idx]`
+    access stays safe (renders as $0.00 / 0.0% — accurate "no data").
+    """
+    rows = list(getattr(snap, "weekly_periods", None) or []) if snap else []
+    # weekly_periods is newest-first (see _dashboard_build_weekly_periods).
+    # Take the newest 8 and reverse to oldest→newest — the Recap template
+    # reads weeks[0] as the start anchor and weeks[-1] as the right-edge
+    # (current-week) anchor, and current_week_index addresses that order.
+    rows_8 = list(reversed(rows[:8]))
+    weeks: list[dict] = []
+    current_idx = 0
+    for i, r in enumerate(rows_8):
+        if getattr(r, "is_current", False):
+            current_idx = i
+        # WeeklyPeriodRow.week_start_at is an ISO datetime string; the
+        # Recap shape wants a YYYY-MM-DD date label. Slice the leading
+        # 10 chars (or fall back to parsing).
+        wsa = getattr(r, "week_start_at", "") or ""
+        start_date = wsa[:10] if isinstance(wsa, str) and len(wsa) >= 10 else wsa
+        cost = float(getattr(r, "cost_usd", 0.0) or 0.0)
+        used_pct_raw = getattr(r, "used_pct", None)
+        used_pct = (float(used_pct_raw) / 100.0) if used_pct_raw is not None else 0.0
+        dpp = float(getattr(r, "dollar_per_pct", 0.0) or 0.0)
+        # Per-week top_projects: WeeklyPeriodRow doesn't carry a
+        # per-project rollup, but `week_start_at` / `week_end_at` give us
+        # an exact range — aggregate session_entries once per week so the
+        # Recap template's `weeks[i].top_projects` table is meaningful.
+        # 8 queries per share render is the perf trade; cached.
+        week_end_at = getattr(r, "week_end_at", "") or ""
+        top_projects: list[tuple[str, float]] = []
+        try:
+            ws_dt = parse_iso_datetime(wsa, "week_start_at") if isinstance(wsa, str) and wsa else None
+            we_dt = parse_iso_datetime(week_end_at, "week_end_at") if isinstance(week_end_at, str) and week_end_at else None
+        except ValueError:
+            ws_dt = we_dt = None
+        if ws_dt is not None and we_dt is not None:
+            top_projects = _share_top_projects_for_range(ws_dt, we_dt)
+        weeks.append({
+            "start_date":     start_date,
+            "cost_usd":       cost,
+            "pct_used":       used_pct,
+            "dollar_per_pct": dpp,
+            "top_projects":   top_projects,
+        })
+    if not weeks:
+        weeks = [_share_empty_week_stub()]
+    return {"weeks": weeks, "current_week_index": current_idx}
+
+
+def _build_current_week_share_panel_data(options: dict,
+                                          snap: "DataSnapshot | None") -> dict:
+    """Current-week panel_data — KPI strip + daily progression + top projects.
+
+    Synthesized from `DataSnapshot.current_week` + `daily_panel` (no 1:1
+    CLI counterpart, per spec §9.5). `daily_progression` clips the daily
+    panel to the current subscription week.
+    """
+    cw = getattr(snap, "current_week", None) if snap else None
+    daily = list(getattr(snap, "daily_panel", None) or []) if snap else []
+    if cw is None:
+        # Empty-shape fallback — Recap builder renders "no data" gracefully.
+        return {
+            "kpi_cost_usd":       0.0,
+            "kpi_pct_used":       0.0,
+            "kpi_dollar_per_pct": 0.0,
+            "kpi_days_remaining": 0.0,
+            "daily_progression":  [],
+            "top_projects":       [],
+            "week_start_date":    _share_now_utc().strftime("%Y-%m-%d"),
+            "display_tz":         options.get("display_tz", "Etc/UTC"),
+        }
+    week_start = getattr(cw, "week_start_at", None)
+    week_end = getattr(cw, "week_end_at", None)
+    week_start_date = (
+        week_start.strftime("%Y-%m-%d") if isinstance(week_start, dt.datetime)
+        else _share_now_utc().strftime("%Y-%m-%d")
+    )
+    # Days remaining = hours_to_reset / 24
+    days_remaining = 0.0
+    if isinstance(week_end, dt.datetime):
+        remaining = (week_end - _share_now_utc()).total_seconds() / 86400.0
+        days_remaining = max(0.0, remaining)
+    used_pct = float(getattr(cw, "used_pct", 0.0) or 0.0) / 100.0
+    progression: list[dict] = []
+    if isinstance(week_start, dt.datetime):
+        ws_date = week_start.date()
+        # daily_panel is newest-first; iterate reversed so progression is
+        # oldest→newest, matching the Recap template's progression[-1] =
+        # today contract and the chart's left→right time axis.
+        for r in reversed(daily):
+            try:
+                d = dt.date.fromisoformat(getattr(r, "date", "") or "")
+            except ValueError:
+                continue
+            if d >= ws_date:
+                progression.append({
+                    "date":     d.isoformat(),
+                    "cost_usd": float(getattr(r, "cost_usd", 0.0) or 0.0),
+                })
+    # Current-week top_projects: aggregate from `[week_start, now]`.
+    # `cw.week_end_at` is the reset instant; using `now` keeps the rollup
+    # symmetric with the panel's "spent this week" KPI (week-to-date).
+    top_projects: list[tuple[str, float]] = []
+    if isinstance(week_start, dt.datetime):
+        top_projects = _share_top_projects_for_range(
+            week_start, _share_now_utc(),
+        )
+    return {
+        "kpi_cost_usd":       float(getattr(cw, "spent_usd", 0.0) or 0.0),
+        "kpi_pct_used":       used_pct,
+        "kpi_dollar_per_pct": float(getattr(cw, "dollars_per_percent", 0.0) or 0.0),
+        "kpi_days_remaining": days_remaining,
+        "daily_progression":  progression,
+        "top_projects":       top_projects,
+        "week_start_date":    week_start_date,
+        "display_tz":         options.get("display_tz", "Etc/UTC"),
+    }
+
+
+def _build_trend_share_panel_data(options: dict,
+                                   snap: "DataSnapshot | None") -> dict:
+    """Trend panel_data — 8 weeks of $/% + 3-week delta KPI.
+
+    Reuses `DataSnapshot.trend` (TuiTrendRow list, already 8 rows).
+    """
+    trend = list(getattr(snap, "trend", None) or []) if snap else []
+    weeks: list[dict] = []
+    for r in trend:
+        wsa = getattr(r, "week_start_at", None)
+        start_date = (
+            wsa.strftime("%Y-%m-%d") if isinstance(wsa, dt.datetime)
+            else (str(wsa)[:10] if wsa else "")
+        )
+        used_pct_raw = getattr(r, "used_pct", None)
+        used_pct = (float(used_pct_raw) / 100.0) if used_pct_raw is not None else 0.0
+        dpp = float(getattr(r, "dollars_per_percent", 0.0) or 0.0)
+        weeks.append({
+            "start_date":     start_date,
+            "cost_usd":       dpp * (used_pct * 100.0),  # ≈ row total
+            "pct_used":       used_pct,
+            "dollar_per_pct": dpp,
+        })
+    # Compute 3-week delta: compare last row vs row-4-from-end.
+    delta = {"dpp_change_pct": 0.0, "cost_change_usd": 0.0}
+    if len(weeks) >= 4:
+        cur = weeks[-1]
+        ref = weeks[-4]
+        if ref["dollar_per_pct"]:
+            delta["dpp_change_pct"] = (
+                (cur["dollar_per_pct"] - ref["dollar_per_pct"]) / ref["dollar_per_pct"]
+            )
+        delta["cost_change_usd"] = cur["cost_usd"] - ref["cost_usd"]
+    return {"weeks": weeks, "delta_3_weeks": delta}
+
+
+def _build_daily_share_panel_data(options: dict,
+                                   snap: "DataSnapshot | None") -> dict:
+    """Daily panel_data — last 7 days with top model per day + top projects.
+
+    Reuses `DataSnapshot.daily_panel` (DailyPanelRow list, 30 rows in
+    full); clips to the most recent 7 for the Recap.
+    """
+    daily = list(getattr(snap, "daily_panel", None) or []) if snap else []
+    # daily_panel is newest-first (today at index 0); take the most recent
+    # 7 and reverse to oldest→newest so the Recap template's days[-1]
+    # anchor lands on today.
+    last_7 = list(reversed(daily[:7]))
+    total = sum(float(getattr(r, "cost_usd", 0.0) or 0.0) for r in last_7) or 1.0
+    days: list[dict] = []
+    for r in last_7:
+        cost = float(getattr(r, "cost_usd", 0.0) or 0.0)
+        models = getattr(r, "models", None) or []
+        top_model = (models[0].get("model") if models else None) or "—"
+        days.append({
+            "date":          getattr(r, "date", "") or "",
+            "cost_usd":      cost,
+            "pct_of_period": cost / total,
+            "top_model":     top_model,
+        })
+    # Daily top_projects: aggregate over the 7-day window. Derive the
+    # range from the dates rendered above so the rollup covers exactly
+    # what the panel shows (rather than re-deriving "7 days ago" from
+    # now and potentially clipping the oldest bucket).
+    top_projects: list[tuple[str, float]] = []
+    if days:
+        try:
+            range_start = dt.datetime.fromisoformat(
+                f"{days[0]['date']}T00:00:00+00:00"
+            )
+            # Include the last day in full — end-exclusive boundary at
+            # the start of the next UTC day.
+            last_date = dt.date.fromisoformat(days[-1]["date"])
+            range_end = dt.datetime(
+                last_date.year, last_date.month, last_date.day,
+                tzinfo=dt.timezone.utc,
+            ) + dt.timedelta(days=1)
+            top_projects = _share_top_projects_for_range(range_start, range_end)
+        except (ValueError, KeyError):
+            top_projects = []
+    return {"days": days, "top_projects": top_projects}
+
+
+def _build_monthly_share_panel_data(options: dict,
+                                     snap: "DataSnapshot | None") -> dict:
+    """Monthly panel_data — last 12 months + top projects.
+
+    Reuses `DataSnapshot.monthly_periods` (MonthlyPeriodRow list).
+    `used_pct` isn't stored on MonthlyPeriodRow (monthly aggregates
+    don't carry a subscription-quota %), so it surfaces as 0.0.
+    """
+    rows = list(getattr(snap, "monthly_periods", None) or []) if snap else []
+    # monthly_periods is newest-first (see _dashboard_build_monthly_periods).
+    # Reverse to oldest→newest — the Recap template reads months[0] as the
+    # period-start anchor and months[-1] as the most recent month.
+    rows = list(reversed(rows))
+    months: list[dict] = []
+    for r in rows:
+        models = getattr(r, "models", None) or []
+        top_model = (models[0].get("model") if models else None) or "—"
+        months.append({
+            "month":     getattr(r, "label", "") or "",  # "YYYY-MM"
+            "cost_usd":  float(getattr(r, "cost_usd", 0.0) or 0.0),
+            "pct_used":  0.0,
+            "top_model": top_model,
+        })
+    # Monthly top_projects: aggregate across the entire 12-month window.
+    # Range = [first day of oldest month, last day of newest month + 1].
+    top_projects: list[tuple[str, float]] = []
+    if months:
+        try:
+            oldest_year, oldest_month = months[0]["month"].split("-")
+            newest_year, newest_month = months[-1]["month"].split("-")
+            range_start = dt.datetime(
+                int(oldest_year), int(oldest_month), 1,
+                tzinfo=dt.timezone.utc,
+            )
+            # End-exclusive: first day of the month AFTER the newest one.
+            ny, nm = int(newest_year), int(newest_month) + 1
+            if nm == 13:
+                ny += 1
+                nm = 1
+            range_end = dt.datetime(ny, nm, 1, tzinfo=dt.timezone.utc)
+            top_projects = _share_top_projects_for_range(range_start, range_end)
+        except (ValueError, KeyError):
+            top_projects = []
+    return {"months": months, "top_projects": top_projects}
+
+
+def _build_forecast_share_panel_data(options: dict,
+                                      snap: "DataSnapshot | None") -> dict:
+    """Forecast panel_data — projection + per-day budgets + days-to-ceiling.
+
+    Reuses `DataSnapshot.forecast` (ForecastOutput).
+    `projection_curve` is synthesized from `r_avg` / `r_recent` /
+    `inputs.p_now` — the same arithmetic `snapshot_to_envelope` does for
+    `week_avg_projection_pct` / `recent_24h_projection_pct`, extended
+    across the next 7 days.
+    """
+    fc = getattr(snap, "forecast", None) if snap else None
+    if fc is None:
+        return {
+            "projected_end_pct":  0.0,
+            "days_to_100pct":     0.0,
+            "days_to_90pct":      0.0,
+            "daily_budgets": {
+                "avg": 0.0, "recent_24h": 0.0,
+                "until_90pct": 0.0, "until_100pct": 0.0,
+            },
+            "projection_curve": [],
+            "confidence":       "LOW CONF",
+        }
+    inputs = getattr(fc, "inputs", None)
+    p_now = float(getattr(inputs, "p_now", 0.0) or 0.0) if inputs else 0.0
+    remaining_hours = float(
+        getattr(inputs, "remaining_hours", 0.0) or 0.0
+    ) if inputs else 0.0
+    confidence = getattr(inputs, "confidence", "ok") if inputs else "ok"
+    r_avg = float(getattr(fc, "r_avg", 0.0) or 0.0)
+    r_recent_raw = getattr(fc, "r_recent", None)
+    r_recent = float(r_recent_raw) if r_recent_raw is not None else r_avg
+    # End-of-week projected %
+    projected_end_pct = (p_now + r_avg * remaining_hours) / 100.0
+    # Days to ceilings (simple inverse: hours-to-target / 24)
+    def _days_to_ceiling(target_pct: float) -> float:
+        if r_avg <= 0 or p_now >= target_pct:
+            return 0.0
+        hours = (target_pct - p_now) / r_avg
+        return max(0.0, hours / 24.0)
+    days_to_100 = _days_to_ceiling(100.0)
+    days_to_90 = _days_to_ceiling(90.0)
+    # Daily budgets — pull from fc.budgets[] when present
+    budgets: dict = {"avg": 0.0, "recent_24h": 0.0,
+                     "until_90pct": 0.0, "until_100pct": 0.0}
+    for b in getattr(fc, "budgets", None) or []:
+        tp = getattr(b, "target_percent", None)
+        dpd = float(getattr(b, "dollars_per_day", 0.0) or 0.0)
+        if tp == 100:
+            budgets["until_100pct"] = dpd
+        elif tp == 90:
+            budgets["until_90pct"] = dpd
+    # avg / recent_24h: derive from dollars-per-percent × r_avg/r_recent.
+    dpp = float(getattr(inputs, "dollars_per_percent", 0.0) or 0.0) if inputs else 0.0
+    budgets["avg"] = dpp * r_avg * 24.0
+    budgets["recent_24h"] = dpp * r_recent * 24.0
+    # Projection curve — 7-day forward, using r_avg
+    today = _share_now_utc().date()
+    projection_curve: list[dict] = []
+    for i in range(7):
+        d = today + dt.timedelta(days=i)
+        pct = (p_now + r_avg * (i * 24.0)) / 100.0
+        projection_curve.append({
+            "date":               d.isoformat(),
+            "projected_pct_used": pct,
+        })
+    return {
+        "projected_end_pct":  projected_end_pct,
+        "days_to_100pct":     days_to_100,
+        "days_to_90pct":      days_to_90,
+        "daily_budgets":      budgets,
+        "projection_curve":   projection_curve,
+        "confidence":         confidence,
+    }
+
+
+def _build_blocks_share_panel_data(options: dict,
+                                    snap: "DataSnapshot | None") -> dict:
+    """Blocks panel_data — current 5h block KPI + 8 recent blocks + top projects.
+
+    Reuses `DataSnapshot.blocks_panel` (BlocksPanelRow list). Current
+    block is the row with `is_active=True`; recent_blocks are the last 8.
+    """
+    rows = list(getattr(snap, "blocks_panel", None) or []) if snap else []
+    current = next((r for r in rows if getattr(r, "is_active", False)), None)
+    cb: dict = {}
+    if current is not None:
+        cb = {
+            "start_at":     _share_iso(getattr(current, "start_at", None)) or "",
+            "end_at":       _share_iso(getattr(current, "end_at", None)) or "",
+            "cost_usd":     float(getattr(current, "cost_usd", 0.0) or 0.0),
+            "pct_used":     0.0,  # BlocksPanelRow doesn't carry a %
+            "tokens_total": 0,    # BlocksPanelRow drops token counts
+        }
+    # blocks_panel is newest-first (see _dashboard_build_blocks_panel:
+    # `rows.sort(key=lambda r: r.start_at, reverse=True)`). Take the most
+    # recent 8 blocks and reverse to oldest→newest so the template's chart
+    # (uses enumerate(recent) for x-position) plots left→right time order.
+    recent: list[dict] = []
+    for r in list(reversed(rows[:8])):
+        recent.append({
+            "start_at": _share_iso(getattr(r, "start_at", None)) or "",
+            "cost_usd": float(getattr(r, "cost_usd", 0.0) or 0.0),
+        })
+    # Blocks top_projects: aggregate across the window covered by
+    # `recent_blocks` (the oldest block's start through the most recent
+    # block's end — also the active block, if any). Mirrors what the
+    # panel actually shows the user.
+    top_projects: list[tuple[str, float]] = []
+    if recent:
+        try:
+            range_start = parse_iso_datetime(
+                recent[0]["start_at"], "blocks.recent_blocks[0].start_at",
+            )
+            # Pick the end of the latest block. `recent` is oldest→newest
+            # after the slice/reverse, so `recent[-1]` is the most recent.
+            # Each block is 5 hours long; if `current_block` has an
+            # explicit `end_at`, prefer that since it may be the active
+            # block whose end_at lives in the future.
+            if cb.get("end_at"):
+                range_end = parse_iso_datetime(
+                    cb["end_at"], "blocks.current_block.end_at",
+                )
+            else:
+                range_end = parse_iso_datetime(
+                    recent[-1]["start_at"], "blocks.recent_blocks[-1].start_at",
+                ) + dt.timedelta(hours=5)
+            top_projects = _share_top_projects_for_range(range_start, range_end)
+        except (ValueError, KeyError):
+            top_projects = []
+    return {
+        "current_block": cb,
+        "recent_blocks": recent,
+        "top_projects":  top_projects,
+    }
+
+
+def _build_sessions_share_panel_data(options: dict,
+                                      snap: "DataSnapshot | None") -> dict:
+    """Sessions panel_data — top N sessions table.
+
+    Reuses `DataSnapshot.sessions` (TuiSessionRow list). Truncated to
+    `options.top_n` (default 15) by upstream cap before the Recap builder
+    runs its own slice.
+    """
+    rows = list(getattr(snap, "sessions", None) or []) if snap else []
+    top_n = options.get("top_n", 15)
+    try:
+        top_n_int = max(1, int(top_n))
+    except (TypeError, ValueError):
+        top_n_int = 15
+    sessions: list[dict] = []
+    for r in rows[:top_n_int]:
+        sessions.append({
+            "session_id":   getattr(r, "session_id", "") or "",
+            "project_path": getattr(r, "project_label", "") or "",
+            "cost_usd":     float(getattr(r, "cost_usd", 0.0) or 0.0),
+            "started_at":   _share_iso(getattr(r, "started_at", None)) or "",
+            "model":        getattr(r, "model_primary", "") or "",
+        })
+    return {"sessions": sessions}
+
+
 def _share_render_and_emit(snap, args) -> None:
     """End-to-end: scrub -> render -> emit -> optional open.
 
@@ -32215,6 +33087,12 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
             self._handle_get_update_status()
         elif path.startswith("/api/update/stream/"):
             self._handle_get_update_stream(path)
+        elif path == "/api/share/templates":
+            self._handle_share_templates_get()
+        elif path == "/api/share/presets":
+            self._handle_share_presets_get()
+        elif path == "/api/share/history":
+            self._handle_share_history_get()
         else:
             self.send_error(404, "not found")
 
@@ -32230,6 +33108,14 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
             self._handle_post_update()
         elif path == "/api/update/dismiss":
             self._handle_post_update_dismiss()
+        elif path == "/api/share/render":
+            self._handle_share_render_post()
+        elif path == "/api/share/compose":
+            self._handle_share_compose_post()
+        elif path == "/api/share/presets":
+            self._handle_share_presets_post()
+        elif path == "/api/share/history":
+            self._handle_share_history_post()
         else:
             self.send_error(404, "not found")
 
@@ -32247,6 +33133,13 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
     def do_DELETE(self) -> None:  # noqa: N802 — stdlib API
         if self._method_not_allowed_for_settings():
             return
+        path = self.path.split("?", 1)[0]
+        if path.startswith("/api/share/presets/"):
+            self._handle_share_presets_delete()
+            return
+        if path == "/api/share/history":
+            self._handle_share_history_delete()
+            return
         self.send_error(501, "Unsupported method ('DELETE')")
 
     def do_PATCH(self) -> None:  # noqa: N802 — stdlib API
@@ -32771,6 +33664,766 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
         status = _dispatch_alert_notification(payload, mode="test")
         self._respond_json(200, {"alert": payload, "dispatch": status})
 
+    # ---- share endpoints (spec §5.1) ----------------------------------
+    #
+    # GET  /api/share/templates?panel=<id> → list Recap/Visual/Detail
+    #      templates registered in _lib_share_templates for that panel.
+    # POST /api/share/render               → render one panel-section to
+    #      body via the kernel; returns {body, content_type, snapshot}
+    #      with kernel_version + data_digest for v2 composer drift checks.
+    #
+    # The template registry is late-imported per-request to keep dashboard
+    # startup cheap — matches cmd_tui's `rich` lazy-import pattern. Same
+    # late-load applies to the kernel (`_lib_share`) via `_share_load_lib`.
+    # GET is unauthenticated (idempotent read). POST gates on
+    # `_check_origin_csrf` (same convention as /api/sync, /api/settings).
+
+    def _share_load_templates_module(self):
+        """Late-load the share-templates registry, cached in sys.modules.
+
+        Keeps dashboard startup zero-cost — the registry only imports when
+        the first share request arrives. Subsequent requests reuse the
+        sys.modules entry; matches the `_share_load_lib` convention so
+        ShareTemplate identity stays stable across calls.
+        """
+        cached = sys.modules.get("_lib_share_templates")
+        if cached is not None:
+            return cached
+        import importlib.util as _ilu
+        p = pathlib.Path(__file__).resolve().parent / "_lib_share_templates.py"
+        spec = _ilu.spec_from_file_location("_lib_share_templates", p)
+        mod = _ilu.module_from_spec(spec)
+        sys.modules["_lib_share_templates"] = mod
+        try:
+            spec.loader.exec_module(mod)
+        except Exception:
+            sys.modules.pop("_lib_share_templates", None)
+            raise
+        return mod
+
+    def _handle_share_templates_get(self) -> None:
+        """List share templates registered for the requested panel.
+
+        Query: ?panel=<id>. Rejects missing or non-share-capable panels
+        (e.g., `alerts`) with 400 + {error, field} envelope (matches
+        existing dashboard error shape; see spec §5.5).
+        """
+        import urllib.parse as _urlparse
+        qs = _urlparse.urlparse(self.path).query
+        params = _urlparse.parse_qs(qs)
+        panel = (params.get("panel", [""])[0] or "").strip()
+        if not panel:
+            self._respond_json(400, {
+                "error": "missing query param: panel",
+                "field": "panel",
+            })
+            return
+        tpl_mod = self._share_load_templates_module()
+        if panel not in tpl_mod.SHARE_CAPABLE_PANELS:
+            self._respond_json(400, {
+                "error": f"unknown share panel: {panel!r}",
+                "field": "panel",
+            })
+            return
+        templates = [
+            {
+                "id": t.id,
+                "label": t.label,
+                "description": t.description,
+                "default_options": dict(t.default_options),
+            }
+            for t in tpl_mod.templates_for_panel(panel)
+        ]
+        self._respond_json(200, {"panel": panel, "templates": templates})
+
+    def _handle_share_render_post(self) -> None:
+        """Render a panel-section to body via the share kernel.
+
+        Body shape: ``{panel, template_id, options}``. Validates panel +
+        template_id against the registry, dispatches to the per-panel
+        `_build_<panel>_share_panel_data` helper to assemble the
+        builder-shaped dict from the current dashboard snapshot, runs the
+        template's builder, applies `_scrub` when
+        ``options.reveal_projects`` is False, then renders via
+        `_lib_share.render`. Response: ``{body, content_type, snapshot}``
+        where `snapshot` carries `kernel_version` + `data_digest` for the
+        v2 composer's drift detection (spec §5.2).
+
+        CSRF: Origin/Host parity via `_check_origin_csrf` — same gate as
+        `/api/sync`, `/api/settings`, `/api/alerts/test`.
+        """
+        if not self._check_origin_csrf():
+            return
+        try:
+            length = int(self.headers.get("Content-Length", "0") or "0")
+        except ValueError:
+            length = 0
+        try:
+            raw = self.rfile.read(length) if length > 0 else b""
+            req = json.loads(raw) if raw else {}
+        except (ValueError, json.JSONDecodeError):
+            self._respond_json(400, {"error": "malformed json"})
+            return
+        if not isinstance(req, dict):
+            self._respond_json(400, {"error": "expected JSON object"})
+            return
+        panel = req.get("panel")
+        template_id = req.get("template_id")
+        options = req.get("options") or {}
+        if not isinstance(options, dict):
+            self._respond_json(400, {
+                "error": "options must be an object",
+                "field": "options",
+            })
+            return
+        if not isinstance(panel, str) or not panel:
+            self._respond_json(400, {
+                "error": "missing or non-string panel",
+                "field": "panel",
+            })
+            return
+        if not isinstance(template_id, str) or not template_id:
+            self._respond_json(400, {
+                "error": "missing or non-string template_id",
+                "field": "template_id",
+            })
+            return
+        fmt = options.get("format", "html")
+        if fmt not in ("md", "html", "svg"):
+            self._respond_json(400, {
+                "error": f"unknown format: {fmt!r}",
+                "field": "options.format",
+            })
+            return
+        theme = options.get("theme", "light")
+        if theme not in ("light", "dark"):
+            self._respond_json(400, {
+                "error": f"unknown theme: {theme!r}",
+                "field": "options.theme",
+            })
+            return
+        # `top_n` may be explicit-null when the UI's Top-N input is
+        # cleared (Knobs.tsx:43); treat null as "use template default"
+        # rather than 400-ing every preview/export until the user types
+        # a number.
+        if options.get("top_n") is not None:
+            top_n_raw = options["top_n"]
+            if not isinstance(top_n_raw, int) or isinstance(top_n_raw, bool) or top_n_raw < 1:
+                self._respond_json(400, {
+                    "error": f"top_n must be a positive integer, got {top_n_raw!r}",
+                    "field": "options.top_n",
+                })
+                return
+
+        tpl_mod = self._share_load_templates_module()
+        if panel not in tpl_mod.SHARE_CAPABLE_PANELS:
+            self._respond_json(400, {
+                "error": f"unknown share panel: {panel!r}",
+                "field": "panel",
+            })
+            return
+        try:
+            template = tpl_mod.get_template(template_id)
+        except KeyError:
+            self._respond_json(400, {
+                "error": f"unknown template_id: {template_id!r}",
+                "field": "template_id",
+            })
+            return
+        if template.panel != panel:
+            self._respond_json(400, {
+                "error": (
+                    f"template_id {template_id!r} belongs to panel "
+                    f"{template.panel!r}, not {panel!r}"
+                ),
+                "field": "template_id",
+            })
+            return
+
+        # Build panel_data from the live dashboard snapshot — reuses the
+        # already-built `DataSnapshot` so we don't re-query the DB on the
+        # share hot path. `_build_share_panel_data` dispatches per panel.
+        snap_ref = type(self).snapshot_ref
+        data_snap = snap_ref.get() if snap_ref is not None else None
+        # Period override (current / previous / custom). For
+        # `kind='current'` (the default) this is a no-op; otherwise we
+        # re-build the relevant panel's DataSnapshot field from DB with
+        # a shifted `now_utc` before slicing.
+        data_snap, period_err = _share_apply_period_override(panel, options,
+                                                              data_snap)
+        if period_err is not None:
+            self._respond_json(400, period_err)
+            return
+        try:
+            panel_data = _build_share_panel_data(panel, options, data_snap)
+        except Exception as exc:
+            self._respond_json(500, {"error": f"panel_data build failed: {exc}"})
+            return
+
+        # Run template builder → kernel render. Builder produces a
+        # ShareSnapshot; `_scrub` anonymizes project labels when the
+        # client opted in to anon-on-export (`reveal_projects=False`).
+        ls = _share_load_lib()
+        try:
+            snap_built = template.builder(panel_data=panel_data, options=options)
+        except Exception as exc:
+            self._respond_json(500, {"error": f"builder failed: {exc}"})
+            return
+        snap_built = replace(snap_built, template_id=template_id)
+        # Content toggles (spec §Q4). Defaults match the existing
+        # behavior (chart on, table on); explicit False strips the
+        # corresponding section from the ShareSnapshot. ShareSnapshot
+        # is frozen so we use dataclasses.replace.
+        snap_built = _share_apply_content_toggles(snap_built, options)
+        reveal = bool(options.get("reveal_projects", True))
+        if not reveal:
+            snap_built = ls._scrub(snap_built, reveal_projects=False)
+        try:
+            body = ls.render(
+                snap_built,
+                format=fmt,
+                theme=options.get("theme", "light"),
+                branding=not options.get("no_branding", False),
+            )
+        except Exception as exc:
+            self._respond_json(500, {"error": f"render failed: {exc}"})
+            return
+        content_type = {
+            "md":   "text/markdown",
+            "html": "text/html",
+            "svg":  "image/svg+xml",
+        }[fmt]
+
+        # data_digest hashes the inputs that identify the underlying DATA
+        # (panel + template + panel_data), NOT rendering toggles like theme
+        # / branding / reveal_projects / format. Used by the composer to
+        # detect "section data has drifted since add-time" (spec §5.2 /
+        # §7.1) — flipping anon-on-export must not register as drift, since
+        # the underlying data is identical.
+        digest_input = {
+            "panel": panel,
+            "template_id": template_id,
+            "panel_data": panel_data,
+        }
+        try:
+            data_digest = ls._data_digest(digest_input)
+        except Exception:
+            # Defensive: digest is non-blocking for the response — fall
+            # back to an empty string and let the composer treat it as
+            # "always drifted" rather than failing the whole render.
+            data_digest = ""
+
+        self._respond_json(200, {
+            "body": body,
+            "content_type": content_type,
+            "snapshot": {
+                "kernel_version": ls.KERNEL_VERSION,
+                "panel": panel,
+                "template_id": template_id,
+                "options": options,
+                "generated_at": _share_now_utc_iso(),
+                "data_digest": data_digest,
+            },
+        })
+
+    # ---- /api/share/compose — stitch many basket sections (spec §5.3) ----
+
+    def _handle_share_compose_post(self) -> None:
+        """Stitch multiple panel sections into one composed document.
+
+        Recipe-only. The server re-renders every section from its
+        ``(panel, template_id, options)`` recipe — never accepting a client-
+        supplied ``body``. Per-section drift detection compares the fresh
+        ``data_digest`` against the client's ``data_digest_at_add``;
+        mismatches surface as ``section_results[i].drift_detected = true``
+        for the composer's "Outdated" badge.
+
+        Spec §5.3, §10.3. CSRF-gated.
+        """
+        if not self._check_origin_csrf():
+            return
+        try:
+            length = int(self.headers.get("Content-Length", "0") or "0")
+        except ValueError:
+            length = 0
+        try:
+            raw = self.rfile.read(length) if length > 0 else b""
+            req = json.loads(raw) if raw else {}
+        except (ValueError, json.JSONDecodeError):
+            self._respond_json(400, {"error": "malformed json"})
+            return
+        if not isinstance(req, dict):
+            self._respond_json(400, {"error": "expected JSON object"})
+            return
+
+        title = req.get("title")
+        theme = req.get("theme", "light")
+        fmt = req.get("format", "html")
+        no_branding = bool(req.get("no_branding", False))
+        reveal_projects = bool(req.get("reveal_projects", False))
+        sections_in = req.get("sections")
+        if not isinstance(title, str) or not title:
+            self._respond_json(400, {"error": "missing title", "field": "title"})
+            return
+        if theme not in ("light", "dark"):
+            self._respond_json(400, {"error": f"unknown theme: {theme!r}",
+                                      "field": "theme"})
+            return
+        if fmt not in ("md", "html", "svg"):
+            self._respond_json(400, {"error": f"unknown format: {fmt!r}",
+                                      "field": "format"})
+            return
+        if not isinstance(sections_in, list) or not sections_in:
+            self._respond_json(400, {
+                "error": "sections must be a non-empty array",
+                "field": "sections",
+            })
+            return
+
+        tpl_mod = self._share_load_templates_module()
+        ls = _share_load_lib()
+        snap_ref = type(self).snapshot_ref
+        data_snap = snap_ref.get() if snap_ref is not None else None
+
+        composed_sections: list = []
+        section_results: list[dict] = []
+
+        for idx, sec in enumerate(sections_in):
+            if not isinstance(sec, dict):
+                self._respond_json(400, {
+                    "error": f"sections[{idx}] must be an object",
+                    "field": f"sections[{idx}]",
+                })
+                return
+            # Explicit: client-supplied `body` and `content_type` are
+            # silently IGNORED. This is the privacy chokepoint — the
+            # regression test in tests/test_api_share.py guards it.
+            snap_recipe = sec.get("snapshot") or {}
+            panel = snap_recipe.get("panel")
+            template_id = snap_recipe.get("template_id")
+            sec_opts = snap_recipe.get("options") or {}
+            digest_at_add = snap_recipe.get("data_digest_at_add") or ""
+            if (not isinstance(panel, str)
+                    or panel not in tpl_mod.SHARE_CAPABLE_PANELS):
+                self._respond_json(400, {
+                    "error": (
+                        f"sections[{idx}].snapshot.panel invalid: {panel!r}"
+                    ),
+                    "field": f"sections[{idx}].snapshot.panel",
+                })
+                return
+            try:
+                template = tpl_mod.get_template(template_id)
+            except KeyError:
+                self._respond_json(400, {
+                    "error": (
+                        f"sections[{idx}].snapshot.template_id "
+                        f"unknown: {template_id!r}"
+                    ),
+                    "field": f"sections[{idx}].snapshot.template_id",
+                })
+                return
+            if template.panel != panel:
+                self._respond_json(400, {
+                    "error": (f"sections[{idx}].snapshot.template_id "
+                              f"{template_id!r} belongs to panel "
+                              f"{template.panel!r}, not {panel!r}"),
+                    "field": f"sections[{idx}].snapshot.template_id",
+                })
+                return
+
+            # Force the composite reveal_projects across every section
+            # (spec §8.5: per-section anon at add-time is ignored at compose).
+            composite_opts = {**sec_opts, "reveal_projects": reveal_projects,
+                              "theme": theme, "format": fmt,
+                              "no_branding": no_branding}
+            # Per-section period override — each basket item carries its
+            # own period recipe, independent of the composite anon flag.
+            sec_snap, period_err = _share_apply_period_override(
+                panel, composite_opts, data_snap,
+            )
+            if period_err is not None:
+                self._respond_json(400, {
+                    "error": f"sections[{idx}]: {period_err['error']}",
+                    "field": f"sections[{idx}].snapshot.{period_err['field']}",
+                })
+                return
+            try:
+                panel_data = _build_share_panel_data(panel, composite_opts,
+                                                     sec_snap)
+            except Exception as exc:
+                self._respond_json(500, {
+                    "error": f"sections[{idx}] panel_data build failed: {exc}",
+                })
+                return
+            try:
+                snap_built = template.builder(panel_data=panel_data,
+                                              options=composite_opts)
+            except Exception as exc:
+                self._respond_json(500, {
+                    "error": f"sections[{idx}] builder failed: {exc}",
+                })
+                return
+            snap_built = replace(snap_built, template_id=template_id)
+            # Same content toggles as the single-section render path.
+            # Per-section `show_chart`/`show_table` from the basket
+            # recipe are applied here; the composite anon flag is
+            # already merged into composite_opts upstream.
+            snap_built = _share_apply_content_toggles(snap_built, composite_opts)
+            if not reveal_projects:
+                snap_built = ls._scrub(snap_built, reveal_projects=False)
+
+            # Defensive: digest is non-blocking metadata — fall back to
+            # "" on failure rather than 500-ing the whole compose
+            # (mirrors the render handler at bin/cctally:33402-33408).
+            try:
+                digest_now = ls._data_digest({
+                    "panel": panel,
+                    "template_id": template_id,
+                    "panel_data": panel_data,
+                })
+            except Exception:
+                digest_now = ""
+            composed_sections.append(ls.ComposedSection(
+                snap=snap_built,
+                drift_detected=(digest_now != digest_at_add),
+            ))
+            section_results.append({
+                "snapshot_id": f"{idx:02d}",
+                "drift_detected": digest_now != digest_at_add,
+                "data_digest_at_add": digest_at_add,
+                "data_digest_now": digest_now,
+            })
+
+        compose_opts = ls.ComposeOptions(
+            title=title, theme=theme, format=fmt,
+            no_branding=no_branding, reveal_projects=reveal_projects,
+        )
+        try:
+            body = ls.compose(tuple(composed_sections), opts=compose_opts)
+        except Exception as exc:
+            self._respond_json(500, {"error": f"compose failed: {exc}"})
+            return
+
+        content_type = {
+            "md":   "text/markdown",
+            "html": "text/html",
+            "svg":  "image/svg+xml",
+        }[fmt]
+        self._respond_json(200, {
+            "body": body,
+            "content_type": content_type,
+            "snapshot": {
+                "kernel_version": ls.KERNEL_VERSION,
+                "composed_at": _share_now_utc_iso(),
+                "section_results": section_results,
+            },
+        })
+
+    # ---- /api/share/presets — saved-recipe CRUD (spec §5.1, §11.3) ----
+    #
+    # GET    /api/share/presets                       → list, grouped by panel
+    # POST   /api/share/presets                       → upsert (panel, name)
+    # DELETE /api/share/presets/{panel}/{name}        → remove one preset
+    #
+    # Persistence: `config.json` under `share.presets[<panel>][<name>]` so
+    # the CLI can read them later (CLI consumer is designed for, not
+    # shipped — out of scope per spec §15). GET is unauthenticated like
+    # `/api/share/templates`; POST + DELETE go through `_check_origin_csrf`
+    # (same gate as `/api/sync`, `/api/settings`, `/api/alerts/test`).
+    # Write discipline: `config_writer_lock` + `_load_config_unlocked` +
+    # `save_config` (atomic `os.replace`). Never call `load_config` from
+    # inside the writer lock — `fcntl.flock` is per-fd and would
+    # self-deadlock; see `_cmd_config_set` for the established pattern.
+
+    def _handle_share_presets_get(self) -> None:
+        """List saved share presets, grouped by panel (spec §5.1, §11.3).
+
+        Read-only — no CSRF gate. `config.json` may not contain the
+        `share.presets` key on first run; returns `{"presets": {}}` then.
+        """
+        cfg = load_config()
+        presets = (cfg.get("share") or {}).get("presets") or {}
+        self._respond_json(200, {"presets": presets})
+
+    def _handle_share_presets_post(self) -> None:
+        """Create or overwrite a preset (idempotent on `(panel, name)`).
+
+        Body: ``{panel, name, template_id, options}``. CSRF-gated.
+
+        Persistence is a read-modify-write under ``config_writer_lock`` +
+        ``_load_config_unlocked``. The plain ``load_config`` would
+        self-deadlock on the same fcntl.flock fd; see the CLAUDE.md
+        config-write invariant and `_cmd_config_set` for the canonical
+        pattern.
+        """
+        if not self._check_origin_csrf():
+            return
+        try:
+            length = int(self.headers.get("Content-Length", "0") or "0")
+        except ValueError:
+            length = 0
+        try:
+            raw = self.rfile.read(length) if length > 0 else b""
+            req = json.loads(raw) if raw else {}
+        except (ValueError, json.JSONDecodeError):
+            self._respond_json(400, {"error": "malformed json"})
+            return
+        if not isinstance(req, dict):
+            self._respond_json(400, {"error": "expected JSON object"})
+            return
+        panel = req.get("panel")
+        name = req.get("name")
+        template_id = req.get("template_id")
+        options = req.get("options")
+        if not isinstance(panel, str) or not panel:
+            self._respond_json(400, {
+                "error": "missing or non-string panel",
+                "field": "panel",
+            })
+            return
+        tpl_mod = self._share_load_templates_module()
+        if panel not in tpl_mod.SHARE_CAPABLE_PANELS:
+            self._respond_json(400, {
+                "error": f"unknown share panel: {panel!r}",
+                "field": "panel",
+            })
+            return
+        if not isinstance(name, str) or not name or "/" in name or len(name) > 64:
+            self._respond_json(400, {
+                "error": "name must be 1-64 chars and contain no '/'",
+                "field": "name",
+            })
+            return
+        if not isinstance(template_id, str) or not template_id:
+            self._respond_json(400, {
+                "error": "missing or non-string template_id",
+                "field": "template_id",
+            })
+            return
+        try:
+            template = tpl_mod.get_template(template_id)
+        except KeyError:
+            self._respond_json(400, {
+                "error": f"unknown template_id: {template_id!r}",
+                "field": "template_id",
+            })
+            return
+        if template.panel != panel:
+            self._respond_json(400, {
+                "error": (
+                    f"template_id {template_id!r} belongs to panel "
+                    f"{template.panel!r}, not {panel!r}"
+                ),
+                "field": "template_id",
+            })
+            return
+        if not isinstance(options, dict):
+            self._respond_json(400, {
+                "error": "options must be an object",
+                "field": "options",
+            })
+            return
+
+        saved_at = _share_now_utc_iso()
+        record = {"template_id": template_id, "options": options, "saved_at": saved_at}
+
+        with config_writer_lock():
+            cfg = _load_config_unlocked()
+            share = cfg.setdefault("share", {})
+            presets = share.setdefault("presets", {})
+            panel_bucket = presets.setdefault(panel, {})
+            panel_bucket[name] = record
+            save_config(cfg)
+        self._respond_json(200, {"panel": panel, "name": name, **record})
+
+    def _handle_share_presets_delete(self) -> None:
+        """Remove a preset by `(panel, name)`.
+
+        Path: ``/api/share/presets/{panel}/{name}``. Missing → 404 so
+        DELETE stays meaningful for idempotency-aware clients. CSRF-gated.
+        """
+        if not self._check_origin_csrf():
+            return
+        import urllib.parse as _urlparse
+        # Strip the query string defensively; the spec only uses path
+        # segments but a stray "?" shouldn't poison the name token.
+        path_only = self.path.split("?", 1)[0]
+        parts = path_only.split("/")
+        # Expected: ["", "api", "share", "presets", "<panel>", "<name>"]
+        if (
+            len(parts) != 6
+            or parts[1] != "api"
+            or parts[2] != "share"
+            or parts[3] != "presets"
+            or not parts[4]
+            or not parts[5]
+        ):
+            self._respond_json(400, {"error": "malformed delete path"})
+            return
+        panel = _urlparse.unquote(parts[4])
+        name = _urlparse.unquote(parts[5])
+        with config_writer_lock():
+            cfg = _load_config_unlocked()
+            share = cfg.get("share") or {}
+            presets = share.get("presets") or {}
+            panel_bucket = presets.get(panel) or {}
+            if name not in panel_bucket:
+                self._respond_json(404, {"error": "no such preset"})
+                return
+            del panel_bucket[name]
+            # Tidy empty buckets so GET stays clean.
+            if not panel_bucket:
+                presets.pop(panel, None)
+            save_config(cfg)
+        self.send_response(204)
+        self.send_header("Content-Length", "0")
+        self.end_headers()
+
+    # ---- /api/share/history — export-recipe ring buffer (spec §5.1, §11.4) ----
+    #
+    # GET    /api/share/history  → list (newest last) of last 20 export recipes
+    # POST   /api/share/history  → append; server-side FIFO trim to 20
+    # DELETE /api/share/history  → clear the entire buffer
+    #
+    # Persisted under `share.history` in `config.json`. Write discipline
+    # matches the presets handlers above: `config_writer_lock` +
+    # `_load_config_unlocked` + `save_config`. GET is unauthenticated
+    # like `/api/share/templates`; POST + DELETE go through
+    # `_check_origin_csrf`. The frontend posts fire-and-forget after
+    # every successful export — history failures are non-fatal.
+
+    def _handle_share_history_get(self) -> None:
+        """Return the recent-shares ring buffer (newest last, spec §11.4)."""
+        cfg = load_config()
+        history = (cfg.get("share") or {}).get("history") or []
+        self._respond_json(200, {"history": history})
+
+    def _handle_share_history_post(self) -> None:
+        """Append a recipe to the ring buffer; FIFO trim to 20.
+
+        Body: ``{panel, template_id, options, format, destination}``. The
+        server stamps ``recipe_id`` (random hex) and ``exported_at``
+        (UTC ISO-8601) so the client doesn't need a clock or a UUID lib.
+        CSRF-gated. Read-modify-write under ``config_writer_lock`` —
+        same pattern as the presets POST.
+        """
+        if not self._check_origin_csrf():
+            return
+        try:
+            length = int(self.headers.get("Content-Length", "0") or "0")
+        except ValueError:
+            length = 0
+        try:
+            raw = self.rfile.read(length) if length > 0 else b""
+            req = json.loads(raw) if raw else {}
+        except (ValueError, json.JSONDecodeError):
+            self._respond_json(400, {"error": "malformed json"})
+            return
+        if not isinstance(req, dict):
+            self._respond_json(400, {"error": "expected JSON object"})
+            return
+        panel = req.get("panel")
+        template_id = req.get("template_id")
+        options = req.get("options") or {}
+        fmt = req.get("format")
+        destination = req.get("destination")
+        if not isinstance(panel, str) or not panel:
+            self._respond_json(400, {
+                "error": "missing or non-string panel",
+                "field": "panel",
+            })
+            return
+        tpl_mod = self._share_load_templates_module()
+        if panel not in tpl_mod.SHARE_CAPABLE_PANELS:
+            self._respond_json(400, {
+                "error": f"unknown share panel: {panel!r}",
+                "field": "panel",
+            })
+            return
+        if not isinstance(template_id, str) or not template_id:
+            self._respond_json(400, {
+                "error": "missing or non-string template_id",
+                "field": "template_id",
+            })
+            return
+        try:
+            template = tpl_mod.get_template(template_id)
+        except KeyError:
+            self._respond_json(400, {
+                "error": f"unknown template_id: {template_id!r}",
+                "field": "template_id",
+            })
+            return
+        if template.panel != panel:
+            self._respond_json(400, {
+                "error": (
+                    f"template_id {template_id!r} belongs to panel "
+                    f"{template.panel!r}, not {panel!r}"
+                ),
+                "field": "template_id",
+            })
+            return
+        if not isinstance(options, dict):
+            self._respond_json(400, {
+                "error": "options must be an object",
+                "field": "options",
+            })
+            return
+        # `format` and `destination` are advisory strings — accept any
+        # non-empty string; the frontend uses them only as display hints
+        # in the dropdown row. None/missing is allowed (mirrors how the
+        # CLI doesn't always know which destination produced the export).
+        if fmt is not None and not isinstance(fmt, str):
+            self._respond_json(400, {
+                "error": "format must be a string if provided",
+                "field": "format",
+            })
+            return
+        if destination is not None and not isinstance(destination, str):
+            self._respond_json(400, {
+                "error": "destination must be a string if provided",
+                "field": "destination",
+            })
+            return
+
+        record = {
+            "recipe_id": _share_history_recipe_id(),
+            "panel": panel,
+            "template_id": template_id,
+            "options": options,
+            "format": fmt,
+            "destination": destination,
+            "exported_at": _share_now_utc_iso(),
+        }
+        with config_writer_lock():
+            cfg = _load_config_unlocked()
+            share = cfg.setdefault("share", {})
+            history = share.setdefault("history", [])
+            history.append(record)
+            # Ring buffer: trim from the front so the newest is always
+            # last. `del history[:n]` keeps the same list instance, so
+            # callers holding a reference (none in this scope, but a
+            # safe invariant) see the same object mutated in place.
+            if len(history) > _SHARE_HISTORY_RING_CAP:
+                del history[: len(history) - _SHARE_HISTORY_RING_CAP]
+            save_config(cfg)
+        self._respond_json(200, record)
+
+    def _handle_share_history_delete(self) -> None:
+        """Empty the share-history ring buffer (spec §11.4)."""
+        if not self._check_origin_csrf():
+            return
+        with config_writer_lock():
+            cfg = _load_config_unlocked()
+            share = cfg.get("share")
+            if isinstance(share, dict) and "history" in share:
+                share["history"] = []
+                save_config(cfg)
+        self.send_response(204)
+        self.send_header("Content-Length", "0")
+        self.end_headers()
+
     # ---- helpers ----
 
     def _respond_json(self, status: int, body: dict) -> None: