radiant-charts-core 0.2.0

package/src/core/CrosshairManager.ts

@@ -0,0 +1,334 @@
+// Radiant Charts - CrosshairRenderer (formerly CrosshairManager)
+// Enhanced: snap dots per series, band highlighting, spike lines, lerp animation
+
+import { Group, Line, Circle, Rect, Text } from '../scene/Shapes';
+import { Theme } from './ThemeManager';
+import { BandScale, safeBandwidth } from '../scale/Scale';
+
+
+/** @deprecated Use `CrosshairRenderer` */
+export type CrosshairManager = CrosshairRenderer;
+
+export class CrosshairRenderer {
+  private group = new Group();
+  private xLine = new Line();
+  private yLine = new Line();
+  private snapDot = new Circle();
+  private bandHighlight = new Rect();
+  private enabledX = false;
+  private enabledY = false;
+
+  /** Pooled per-series snap dots for shared mode */
+  private seriesSnapDots: Circle[] = [];
+  /** Target radii for snap dot scale animation (0 = hidden, 4 = full) */
+  private seriesSnapTargets: number[] = [];
+  /** Spike line axis labels */
+  private spikeXLabel = new Text();
+  private spikeYLabel = new Text();
+  private spikeXBg = new Rect();
+  private spikeYBg = new Rect();
+
+  /** Lerp animation state — target vs current positions */
+  private _targetX = 0;
+  private _targetY = 0;
+  private _currentX = 0;
+  private _currentY = 0;
+  private _lerpActive = false;
+  private static readonly LERP_SPEED = 0.25; // 0–1, higher = faster convergence
+  /** Skip lerp animation when user prefers reduced motion */
+  private _reducedMotion = typeof window !== 'undefined'
+    && window.matchMedia?.('(prefers-reduced-motion: reduce)').matches;
+
+  constructor() {
+    this.group.visible = false;
+
+    this.xLine.strokeWidth = 1;
+    this.yLine.strokeWidth = 1;
+
+    this.snapDot.radius = 5;
+    this.snapDot.fill = 'transparent';
+    this.snapDot.strokeWidth = 2;
+
+    this.bandHighlight.fill = 'rgba(128,128,128,0.06)';
+    this.bandHighlight.visible = false;
+
+    // Spike label defaults
+    this.spikeXLabel.fontSize = 10;
+    this.spikeXLabel.textAlign = 'center';
+    this.spikeXLabel.textBaseline = 'top';
+    this.spikeXLabel.visible = false;
+    this.spikeXBg.cornerRadius = 3;
+    this.spikeXBg.visible = false;
+
+    this.spikeYLabel.fontSize = 10;
+    this.spikeYLabel.textAlign = 'right';
+    this.spikeYLabel.textBaseline = 'middle';
+    this.spikeYLabel.visible = false;
+    this.spikeYBg.cornerRadius = 3;
+    this.spikeYBg.visible = false;
+
+    this.group.add(this.bandHighlight);
+    this.group.add(this.xLine);
+    this.group.add(this.yLine);
+    this.group.add(this.snapDot);
+    this.group.add(this.spikeXBg);
+    this.group.add(this.spikeXLabel);
+    this.group.add(this.spikeYBg);
+    this.group.add(this.spikeYLabel);
+  }
+
+  getGroup() { return this.group; }
+
+  updateOptions(options: { x?: boolean; y?: boolean }) {
+    this.enabledX = options.x ?? false;
+    this.enabledY = options.y ?? false;
+  }
+
+  /**
+   * Show crosshair lines and snap to nearest data point.
+   * If xScale (BandScale) and data are provided, the vertical line snaps to
+   * the nearest category center instead of following the raw mouse X.
+   */
+  show(
+    x: number,
+    y: number,
+    bounds: { x: number; y: number; width: number; height: number },
+    theme: Theme,
+    xScale?: BandScale,
+    data?: readonly any[],
+    xKey?: string
+  ) {
+    if (!this.enabledX && !this.enabledY) {
+      this.group.visible = false;
+      return;
+    }
+
+    this.group.visible = true;
+    const color = theme.axisColor;
+
+    // Snap x to nearest category center
+    let snappedX = x;
+    let snappedY = y;
+    this.snapDot.visible = false;
+    this.bandHighlight.visible = false;
+
+    if (xScale && data && xKey) {
+      let minDist = Infinity;
+      let closestX = x;
+      let closestBandX = 0;
+      for (const d of data) {
+        const catX = xScale.convert(d[xKey]) + safeBandwidth(xScale) / 2;
+        const absX = catX + bounds.x;
+        const dist = Math.abs(absX - x);
+        if (dist < minDist) {
+          minDist = dist;
+          closestX = absX;
+          closestBandX = xScale.convert(d[xKey]);
+        }
+      }
+      snappedX = closestX;
+
+      // Band highlight for BandScale charts
+      if (this.enabledX) {
+        this.bandHighlight.visible = true;
+        this.bandHighlight.x = closestBandX + bounds.x;
+        this.bandHighlight.y = bounds.y;
+        this.bandHighlight.width = safeBandwidth(xScale);
+        this.bandHighlight.height = bounds.height;
+        const isDark = theme.backgroundColor.includes('2') || theme.backgroundColor.includes('0');
+        this.bandHighlight.fill = isDark ? 'rgba(255,255,255,0.05)' : 'rgba(0,0,0,0.04)';
+      }
+
+      // Show snap dot on the crosshair intersection
+      if (this.enabledX) {
+        this.snapDot.visible = true;
+        this.snapDot.centerX = snappedX;
+        this.snapDot.centerY = y;
+        this.snapDot.fill = theme.backgroundColor;
+        this.snapDot.stroke = color;
+      }
+    }
+
+    // Set targets for lerp animation
+    this._targetX = snappedX;
+    this._targetY = snappedY;
+
+    // On first show, snap immediately (no lerp from 0,0)
+    if (!this._lerpActive && this._currentX === 0 && this._currentY === 0) {
+      this._currentX = snappedX;
+      this._currentY = snappedY;
+    } else {
+      this._lerpActive = true;
+    }
+
+    if (this.enabledX) {
+      this.xLine.visible = true;
+      this.xLine.x1 = this._currentX; this.xLine.y1 = bounds.y;
+      this.xLine.x2 = this._currentX; this.xLine.y2 = bounds.y + bounds.height;
+      this.xLine.stroke = color;
+      this.xLine.lineDash = [4, 4];
+    } else {
+      this.xLine.visible = false;
+    }
+
+    if (this.enabledY) {
+      this.yLine.visible = true;
+      this.yLine.x1 = bounds.x;     this.yLine.y1 = this._currentY;
+      this.yLine.x2 = bounds.x + bounds.width; this.yLine.y2 = this._currentY;
+      this.yLine.stroke = color;
+      this.yLine.lineDash = [4, 4];
+    } else {
+      this.yLine.visible = false;
+    }
+
+    // Hide spike labels by default (they're shown via showSeriesSnaps)
+    this.spikeXLabel.visible = false;
+    this.spikeXBg.visible = false;
+    this.spikeYLabel.visible = false;
+    this.spikeYBg.visible = false;
+  }
+
+  /**
+   * Show spike line axis labels at the crosshair intersection with each axis.
+   */
+  showSpikeLabels(
+    xLabel: string,
+    yLabel: string,
+    snappedX: number,
+    snappedY: number,
+    bounds: { x: number; y: number; width: number; height: number },
+    theme: Theme,
+  ) {
+    const isDark = theme.backgroundColor.includes('2') || theme.backgroundColor.includes('0');
+
+    // X-axis spike label
+    if (xLabel && this.enabledX) {
+      this.spikeXLabel.visible = true;
+      this.spikeXLabel.text = xLabel;
+      this.spikeXLabel.x = snappedX;
+      this.spikeXLabel.y = bounds.y + bounds.height + 4;
+      this.spikeXLabel.fill = isDark ? '#e2e8f0' : '#1e293b';
+      this.spikeXLabel.fontFamily = theme.fontFamily;
+
+      // Background badge
+      const tw = xLabel.length * 6 + 12;
+      this.spikeXBg.visible = true;
+      this.spikeXBg.x = snappedX - tw / 2;
+      this.spikeXBg.y = bounds.y + bounds.height + 2;
+      this.spikeXBg.width = tw;
+      this.spikeXBg.height = 18;
+      this.spikeXBg.fill = isDark ? '#1e293b' : '#f1f5f9';
+      this.spikeXBg.stroke = theme.axisColor;
+      this.spikeXBg.strokeWidth = 1;
+    }
+
+    // Y-axis spike label
+    if (yLabel && this.enabledY) {
+      this.spikeYLabel.visible = true;
+      this.spikeYLabel.text = yLabel;
+      this.spikeYLabel.x = bounds.x - 4;
+      this.spikeYLabel.y = snappedY;
+      this.spikeYLabel.fill = isDark ? '#e2e8f0' : '#1e293b';
+      this.spikeYLabel.fontFamily = theme.fontFamily;
+
+      const tw = yLabel.length * 6 + 12;
+      this.spikeYBg.visible = true;
+      this.spikeYBg.x = bounds.x - tw - 4;
+      this.spikeYBg.y = snappedY - 9;
+      this.spikeYBg.width = tw;
+      this.spikeYBg.height = 18;
+      this.spikeYBg.fill = isDark ? '#1e293b' : '#f1f5f9';
+      this.spikeYBg.stroke = theme.axisColor;
+      this.spikeYBg.strokeWidth = 1;
+    }
+  }
+
+  /**
+   * Tick the lerp interpolation one step. Called each RAF frame by ChartManager.
+   * Returns true if the crosshair position changed (scene needs re-render).
+   */
+  tick(): boolean {
+    if (!this.group.visible) return false;
+    // Check if there are any animating snap dots
+    const hasSnapAnim = this.seriesSnapDots.some((d, i) =>
+      Math.abs((this.seriesSnapTargets[i] ?? 0) - d.radius) > 0.2
+    );
+    if (!this._lerpActive && !hasSnapAnim) return false;
+
+    // Skip animation when user prefers reduced motion — snap instantly
+    if (this._reducedMotion) {
+      this._currentX = this._targetX;
+      this._currentY = this._targetY;
+      this._lerpActive = false;
+      if (this.enabledX) { this.xLine.x1 = this._currentX; this.xLine.x2 = this._currentX; }
+      if (this.enabledY) { this.yLine.y1 = this._currentY; this.yLine.y2 = this._currentY; }
+      for (let i = 0; i < this.seriesSnapDots.length; i++) {
+        const dot = this.seriesSnapDots[i];
+        const target = this.seriesSnapTargets[i] ?? 0;
+        dot.radius = target;
+        if (target === 0) dot.visible = false;
+      }
+      return true;
+    }
+
+    const speed = CrosshairRenderer.LERP_SPEED;
+    const dx = this._targetX - this._currentX;
+    const dy = this._targetY - this._currentY;
+
+    // Snap when close enough (sub-pixel)
+    if (Math.abs(dx) < 0.5 && Math.abs(dy) < 0.5) {
+      this._currentX = this._targetX;
+      this._currentY = this._targetY;
+      this._lerpActive = false;
+    } else {
+      this._currentX += dx * speed;
+      this._currentY += dy * speed;
+    }
+
+    // Apply interpolated position to the crosshair lines
+    if (this.enabledX) {
+      this.xLine.x1 = this._currentX;
+      this.xLine.x2 = this._currentX;
+    }
+    if (this.enabledY) {
+      this.yLine.y1 = this._currentY;
+      this.yLine.y2 = this._currentY;
+    }
+
+    // Animate snap dot radii (scale in/out)
+    for (let i = 0; i < this.seriesSnapDots.length; i++) {
+      const dot = this.seriesSnapDots[i];
+      const target = this.seriesSnapTargets[i] ?? 0;
+      const diff = target - dot.radius;
+      if (Math.abs(diff) < 0.2) {
+        dot.radius = target;
+        if (target === 0) dot.visible = false;
+      } else {
+        dot.radius += diff * 0.35;
+      }
+    }
+
+    return true;
+  }
+
+  /** Hide all series snap dots (animated scale-out via tick()) */
+  hideSeriesSnaps() {
+    for (let i = 0; i < this.seriesSnapDots.length; i++) {
+      this.seriesSnapTargets[i] = 0;
+    }
+  }
+
+  hide() {
+    this.group.visible = false;
+    this.bandHighlight.visible = false;
+    this.hideSeriesSnaps();
+    this.spikeXLabel.visible = false;
+    this.spikeXBg.visible = false;
+    this.spikeYLabel.visible = false;
+    this.spikeYBg.visible = false;
+    // Reset lerp so next show starts fresh
+    this._lerpActive = false;
+    this._currentX = 0;
+    this._currentY = 0;
+  }
+}

package/src/core/Legend.ts

@@ -0,0 +1,269 @@
+import { Group, Rect, Text, Circle, Line } from '../scene/Shapes';
+import { Theme } from './ThemeManager';
+
+export interface LegendItem {
+  id: string;
+  label: string;
+  fill: string;
+  markerType?: 'square' | 'circle' | 'line';
+}
+
+/**
+ * Legend: Renders the chart legend with interactive toggle and pagination support.
+ *
+ * Items are wrapped into rows then split into pages so the legend never grows
+ * taller than ~20 % of the chart height.  When multiple pages exist, ◀ / ▶
+ * buttons are rendered in a nav row at the bottom of the legend group.
+ *
+ * ## Click flow
+ * - Series item group  → `seriesId` = the series ID → ChartManager toggles visibility
+ * - Arrow button group → `seriesId` = '__legend_prev__' | '__legend_next__'
+ *                        → ChartManager calls `legend.paginate(±1)`
+ *
+ * ## Hit-testing note
+ * `Text.isPointInNode` always returns false, so arrow buttons wrap the text in
+ * a Group that also contains a transparent Rect that absorbs pointer events.
+ */
+export class Legend {
+  private group   = new Group();
+  private items:  LegendItem[] = [];
+  private theme?: Theme;
+
+  /** Series IDs that the user has toggled off via legend click. */
+  hiddenSeries: string[] = [];
+
+  // ── Pagination state ────────────────────────────────────────────────────────
+  private pages: LegendItem[][] = [];
+  private currentPage = 0;
+
+  // ── Layout constants ────────────────────────────────────────────────────────
+  private readonly ROW_H     = 24;   // px per item row
+  private readonly NAV_H     = 22;   // px for the ◀/▶ row
+  private readonly MARKER    = 12;   // marker square/circle size
+  private readonly GAP       = 6;    // gap between marker and label
+  private readonly SPACING   = 20;   // gap between items on the same row
+  private readonly CHAR_W    = 7.5;  // estimated px per label character
+
+  // Captured in update() and reused by _renderCurrentPage()
+  private lastMaxWidth = 0;
+  private lastMaxRows  = 2;
+
+  // ── Public API ──────────────────────────────────────────────────────────────
+
+  getGroup() { return this.group; }
+
+  setHiddenSeries(ids: string[]) { this.hiddenSeries = ids; }
+  getHiddenSeries(): string[]    { return this.hiddenSeries; }
+
+  update(items: LegendItem[], theme: Theme, maxWidth: number, maxHeight: number, position: string = 'bottom') {
+    this.items  = items;
+    this.theme  = theme;
+    this.lastMaxWidth = maxWidth;
+
+    const isVertical = position === 'left' || position === 'right';
+    const verticalLimitFrac = 0.85; // Reserve up to 85% for side legends
+    const horizontalLimitFrac = 0.25; // Reserve up to 25% for top/bottom legends
+
+    // Reserve space based on orientation; side legends can grow much taller.
+    this.lastMaxRows = Math.max(1, Math.floor((maxHeight * (isVertical ? verticalLimitFrac : horizontalLimitFrac)) / this.ROW_H));
+
+    this.pages = this._buildPages(items, maxWidth, this.lastMaxRows);
+    // Clamp in case items were removed and pages count dropped
+    this.currentPage = Math.min(this.currentPage, Math.max(0, this.pages.length - 1));
+
+    this._renderCurrentPage();
+  }
+
+  /**
+   * Advance (+1) or retreat (−1) one page and re-render.
+   * Called by ChartManager when the ◀ / ▶ arrow is clicked.
+   */
+  paginate(delta: 1 | -1) {
+    this.currentPage = Math.max(0, Math.min(this.pages.length - 1, this.currentPage + delta));
+    this._renderCurrentPage();
+  }
+
+  getBBox() { return this.group.getBBox(); }
+
+  // ── Private helpers ─────────────────────────────────────────────────────────
+
+  /**
+   * Wrap items into rows then chunk rows into pages.
+   *
+   * Two-stage layout:
+   *   1. Pack items left-to-right; start a new row when the current row overflows.
+   *   2. Split the resulting rows into pages of `maxRows` rows each.
+   */
+  private _buildPages(items: LegendItem[], maxWidth: number, maxRows: number): LegendItem[][] {
+    // Stage 1: row-wrap
+    const rows: LegendItem[][] = [];
+    let currentRow: LegendItem[] = [];
+    let currentX = 0;
+
+    for (const item of items) {
+      const itemW = this.MARKER + this.GAP + item.label.length * this.CHAR_W + this.SPACING;
+      if (currentX + itemW > maxWidth && currentRow.length > 0) {
+        rows.push(currentRow);
+        currentRow = [];
+        currentX = 0;
+      }
+      currentRow.push(item);
+      currentX += itemW;
+    }
+    if (currentRow.length > 0) rows.push(currentRow);
+
+    // Stage 2: page-chunk
+    const pages: LegendItem[][] = [];
+    for (let i = 0; i < rows.length; i += maxRows) {
+      pages.push(rows.slice(i, i + maxRows).flat());
+    }
+    return pages.length > 0 ? pages : [[]];
+  }
+
+  /** Rebuild the group's children for the active page. */
+  private _renderCurrentPage() {
+    this.group.clear();
+    if (!this.theme) return;
+
+    const theme = this.theme;
+    const items = this.pages[this.currentPage] ?? [];
+    const multiPage = this.pages.length > 1;
+
+    // ── Series item rows ────────────────────────────────────────────────────
+    let currentX = 0;
+    let currentY = 0;
+
+    for (const item of items) {
+      const labelW    = item.label.length * this.CHAR_W;
+      const totalW    = this.MARKER + this.GAP + labelW;
+
+      if (currentX + totalW > this.lastMaxWidth && currentX > 0) {
+        currentX = 0;
+        currentY += this.ROW_H;
+      }
+
+      const itemGroup = new Group();
+      itemGroup.translation  = { x: currentX, y: currentY };
+      itemGroup.seriesId     = item.id;
+      itemGroup.opacity      = this.hiddenSeries.includes(item.id) ? 0.4 : 1;
+      itemGroup.pointerEvents = true;
+
+      if (item.markerType === 'circle') {
+        const marker = new Circle();
+        marker.centerX = this.MARKER / 2;
+        marker.centerY = this.MARKER / 2;
+        marker.radius  = this.MARKER / 2;
+        marker.fill    = item.fill;
+        itemGroup.add(marker);
+      } else if (item.markerType === 'line') {
+        const marker = new Line();
+        marker.x1 = 0;
+        marker.y1 = this.MARKER / 2;
+        marker.x2 = this.MARKER;
+        marker.y2 = this.MARKER / 2;
+        marker.stroke = item.fill;
+        marker.strokeWidth = 3;
+        itemGroup.add(marker);
+      } else {
+        const marker = new Rect();
+        marker.width        = this.MARKER;
+        marker.height       = this.MARKER;
+        marker.fill         = item.fill;
+        marker.cornerRadius = 2;
+        itemGroup.add(marker);
+      }
+
+      const label = new Text();
+      label.text        = item.label;
+      label.x           = this.MARKER + this.GAP;
+      label.y           = this.MARKER / 2;
+      label.fontSize    = 11;
+      label.fontFamily  = theme.fontFamily;
+      label.fill        = theme.textColor;
+      label.textBaseline = 'middle';
+      itemGroup.add(label);
+
+      this.group.add(itemGroup);
+      currentX += totalW + this.SPACING;
+    }
+
+    // ── Navigation row ──────────────────────────────────────────────────────
+    if (!multiPage) return;
+
+    const navY  = currentY + (items.length > 0 ? this.ROW_H : 0);
+    const muted = theme.subtextColor;
+    const btnH  = this.NAV_H;
+    const btnW  = 28; // clickable width for each arrow button
+
+    // ◀ prev
+    if (this.currentPage > 0) {
+      this.group.add(this._makeNavButton('◀', '__legend_prev__', 0, navY, btnW, btnH, muted, theme, 'start'));
+    }
+
+    // "2 / 5" page indicator (non-interactive)
+    const pageIndicator = new Text();
+    pageIndicator.text        = `${this.currentPage + 1} / ${this.pages.length}`;
+    pageIndicator.x           = this.lastMaxWidth / 2;
+    pageIndicator.y           = navY + btnH / 2;
+    pageIndicator.fontSize    = 10;
+    pageIndicator.fontFamily  = theme.fontFamily;
+    pageIndicator.fill        = muted;
+    pageIndicator.textAlign   = 'center';
+    pageIndicator.textBaseline = 'middle';
+    pageIndicator.pointerEvents = false;
+    this.group.add(pageIndicator);
+
+    // ▶ next
+    if (this.currentPage < this.pages.length - 1) {
+      this.group.add(
+        this._makeNavButton('▶', '__legend_next__', this.lastMaxWidth - btnW, navY, btnW, btnH, muted, theme, 'end'),
+      );
+    }
+  }
+
+  /**
+   * Creates a clickable arrow button: an invisible hit-area Rect behind a Text
+   * arrow glyph, wrapped in a Group tagged with the special seriesId.
+   *
+   * The `Rect` provides a reliably hittable area because `Text.isPointInNode`
+   * always returns false in this scene-graph implementation.
+   */
+  private _makeNavButton(
+    glyph:    string,
+    actionId: '__legend_prev__' | '__legend_next__',
+    x:        number,
+    y:        number,
+    w:        number,
+    h:        number,
+    color:    string,
+    theme:    Theme,
+    align:    CanvasTextAlign,
+  ): Group {
+    const btn = new Group();
+    btn.translation  = { x, y };
+    btn.seriesId     = actionId;
+    btn.pointerEvents = true;
+
+    // Transparent hit-area so the full button region is clickable
+    const hitRect = new Rect();
+    hitRect.x      = 0;
+    hitRect.y      = 0;
+    hitRect.width  = w;
+    hitRect.height = h;
+    hitRect.fill   = 'transparent';
+    btn.add(hitRect);
+
+    const label = new Text();
+    label.text        = glyph;
+    label.x           = align === 'end' ? w : 0;
+    label.y           = h / 2;
+    label.fontSize    = 11;
+    label.fontFamily  = theme.fontFamily;
+    label.fill        = color;
+    label.textAlign   = align;
+    label.textBaseline = 'middle';
+    btn.add(label);
+
+    return btn;
+  }
+}

package/src/core/ThemeManager.ts

@@ -0,0 +1,98 @@
+// Radiant Charts - ThemeManager
+// Phase 1.2: Global Theming System with semantic palettes
+
+export interface ThemePalettes {
+  categorical: string[];
+}
+
+export interface Theme {
+  backgroundColor: string;
+  textColor: string;
+  subtextColor: string;
+  axisColor: string;
+  gridColor: string;
+  /** Default palette (categorical) */
+  palette: string[];
+  palettes: ThemePalettes;
+  fontFamily: string;
+}
+
+// ─── Palettes ────────────────────────────────────────────────────────────────
+
+const CATEGORICAL_LIGHT = [
+  '#4e79a7', '#f28e2c', '#e15759', '#76b7b2',
+  '#59a14f', '#edc948', '#b07aa1', '#ff9da7',
+  '#9c755f', '#bab0ac',
+];
+const CATEGORICAL_DARK = [
+  '#80b1d3', '#fdb462', '#fb8072', '#bebada',
+  '#b3de69', '#fccde5', '#8dd3c7', '#ffffb3',
+  '#bc80bd', '#ccebc5',
+];
+// ─── Built-in Themes ─────────────────────────────────────────────────────────
+
+export const lightTheme: Theme = {
+  backgroundColor: '#ffffff',
+  textColor: '#1a1a2e',
+  subtextColor: '#6b7280',
+  axisColor: '#d1d5db',
+  gridColor: 'rgba(107,114,128,0.12)',
+  palette: CATEGORICAL_LIGHT,
+  palettes: {
+    categorical: CATEGORICAL_LIGHT,
+  },
+  fontFamily: '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif',
+};
+
+export const darkTheme: Theme = {
+  backgroundColor: '#020617',
+  textColor: '#e2e8f0',
+  subtextColor: '#94a3b8',
+  axisColor: '#334155',
+  gridColor: 'rgba(148,163,184,0.08)',
+  palette: CATEGORICAL_DARK,
+  palettes: {
+    categorical: CATEGORICAL_DARK,
+  },
+  fontFamily: '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif',
+};
+
+// ─── ThemeManager ─────────────────────────────────────────────────────────────
+
+export type ThemeOption = 'light' | 'dark' | 'system' | Theme;
+
+/**
+ * Detects whether the OS/browser is currently in dark mode.
+ * Returns false in SSR or when the API is unavailable.
+ */
+function systemPrefersDark(): boolean {
+  if (typeof window === 'undefined') return false;
+  return window.matchMedia('(prefers-color-scheme: dark)').matches;
+}
+
+export class ThemeManager {
+  private currentTheme: Theme = lightTheme;
+
+  setTheme(name: ThemeOption) {
+    if (name === 'light') this.currentTheme = lightTheme;
+    else if (name === 'dark') this.currentTheme = darkTheme;
+    else if (name === 'system') this.currentTheme = systemPrefersDark() ? darkTheme : lightTheme;
+    else this.currentTheme = name as Theme;
+  }
+
+  get theme(): Theme {
+    return this.currentTheme;
+  }
+
+  /**
+   * Resolves whether the given theme option evaluates to dark mode right now.
+   * Useful for UI layers that need an `isDark` boolean without holding a
+   * ThemeManager instance.
+   */
+  static resolveIsDark(option: ThemeOption | undefined): boolean {
+    if (option === 'dark') return true;
+    if (option === 'system') return systemPrefersDark();
+    return false;
+  }
+}
+