liveline 0.0.3 → 0.0.4

package/dist/index.js

@@ -1,17 +1,23 @@
 // src/Liveline.tsx
-import { useRef as useRef2, useState, useLayoutEffect } from "react";
+import { useRef as useRef2, useState, useLayoutEffect, useMemo } from "react";
 
 // src/theme.ts
-function hexToRgb(hex) {
-  const h = hex.replace("#", "");
-  const n = parseInt(h.length === 3 ? h.split("").map((c) => c + c).join("") : h, 16);
-  return [n >> 16 & 255, n >> 8 & 255, n & 255];
+function parseColorRgb(color) {
+  const hex = color.match(/^#([0-9a-f]{3,8})$/i);
+  if (hex) {
+    let h = hex[1];
+    if (h.length === 3) h = h[0] + h[0] + h[1] + h[1] + h[2] + h[2];
+    return [parseInt(h.slice(0, 2), 16), parseInt(h.slice(2, 4), 16), parseInt(h.slice(4, 6), 16)];
+  }
+  const rgb = color.match(/rgba?\(\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)/);
+  if (rgb) return [+rgb[1], +rgb[2], +rgb[3]];
+  return [128, 128, 128];
 }
 function rgba(r, g, b, a) {
   return `rgba(${r}, ${g}, ${b}, ${a})`;
 }
 function resolveTheme(color, mode) {
-  const [r, g, b] = hexToRgb(color);
+  const [r, g, b] = parseColorRgb(color);
   const isDark = mode === "dark";
   return {
     // Line
@@ -97,18 +103,19 @@ function computeRange(visible, currentValue, referenceValue, exaggerate) {
 // src/math/momentum.ts
 function detectMomentum(points, lookback = 20) {
   if (points.length < 5) return "flat";
-  const recent = points.slice(-lookback);
+  const start = Math.max(0, points.length - lookback);
   let min = Infinity;
   let max = -Infinity;
-  for (const p of recent) {
-    if (p.value < min) min = p.value;
-    if (p.value > max) max = p.value;
+  for (let i = start; i < points.length; i++) {
+    const v = points[i].value;
+    if (v < min) min = v;
+    if (v > max) max = v;
   }
   const range = max - min;
   if (range === 0) return "flat";
-  const tail = recent.slice(-5);
-  const first = tail[0].value;
-  const last = tail[tail.length - 1].value;
+  const tailStart = Math.max(start, points.length - 5);
+  const first = points[tailStart].value;
+  const last = points[points.length - 1].value;
   const delta = last - first;
   const threshold = range * 0.12;
   if (delta > threshold) return "up";
@@ -130,7 +137,9 @@ function interpolateAtTime(points, time) {
   }
   const p1 = points[lo];
   const p2 = points[hi];
-  const t = (time - p1.time) / (p2.time - p1.time);
+  const dt = p2.time - p1.time;
+  if (dt === 0) return p1.value;
+  const t = (time - p1.time) / dt;
   return p1.value + (p2.value - p1.value) * t;
 }
 
@@ -212,6 +221,7 @@ function drawGrid(ctx, layout, palette, formatValue, state, dt) {
       state.labels.set(key, target * FADE_IN);
     }
   }
+  const baseAlpha = ctx.globalAlpha;
   ctx.setLineDash([1, 3]);
   ctx.lineWidth = 1;
   ctx.font = palette.labelFont;
@@ -222,7 +232,7 @@ function drawGrid(ctx, layout, palette, formatValue, state, dt) {
     const y = toY(val);
     if (y < pad.top - 10 || y > h - pad.bottom + 10) continue;
     ctx.save();
-    ctx.globalAlpha = alpha;
+    ctx.globalAlpha = baseAlpha * alpha;
     ctx.strokeStyle = palette.gridLine;
     ctx.beginPath();
     ctx.moveTo(pad.left, y);
@@ -287,10 +297,47 @@ function drawSpline(ctx, pts) {
   }
 }
 
+// src/draw/loadingShape.ts
+var LOADING_AMPLITUDE_RATIO = 0.07;
+var LOADING_SCROLL_SPEED = 1e-3;
+function loadingY(t, centerY, amplitude, scroll) {
+  return centerY + amplitude * (Math.sin(t * 9.4 + scroll) * 0.55 + Math.sin(t * 15.7 + scroll * 1.3) * 0.3 + Math.sin(t * 4.2 + scroll * 0.7) * 0.15);
+}
+function loadingBreath(now_ms) {
+  return 0.22 + 0.08 * Math.sin(now_ms / 1200 * Math.PI);
+}
+
 // src/draw/line.ts
-function renderCurve(ctx, layout, palette, pts, showFill) {
+function parseRgba(color) {
+  const hex = color.match(/^#([0-9a-f]{3,8})$/i);
+  if (hex) {
+    let h = hex[1];
+    if (h.length === 3) h = h[0] + h[0] + h[1] + h[1] + h[2] + h[2];
+    return [parseInt(h.slice(0, 2), 16), parseInt(h.slice(2, 4), 16), parseInt(h.slice(4, 6), 16), 1];
+  }
+  const rgba2 = color.match(/rgba\(\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)\s*,\s*([\d.]+)/);
+  if (rgba2) return [+rgba2[1], +rgba2[2], +rgba2[3], +rgba2[4]];
+  const rgb = color.match(/rgb\(\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)/);
+  if (rgb) return [+rgb[1], +rgb[2], +rgb[3], 1];
+  return [128, 128, 128, 1];
+}
+function blendColor(c1, c2, t) {
+  if (t <= 0) return c1;
+  if (t >= 1) return c2;
+  const [r1, g1, b1, a1] = parseRgba(c1);
+  const [r2, g2, b2, a2] = parseRgba(c2);
+  const r = Math.round(r1 + (r2 - r1) * t);
+  const g = Math.round(g1 + (g2 - g1) * t);
+  const b = Math.round(b1 + (b2 - b1) * t);
+  const a = a1 + (a2 - a1) * t;
+  if (a >= 0.995) return `rgb(${r},${g},${b})`;
+  return `rgba(${r},${g},${b},${a.toFixed(3)})`;
+}
+function renderCurve(ctx, layout, palette, pts, showFill, lineAlpha = 1, fillAlpha = 1, strokeColor) {
   const { h, pad } = layout;
-  if (showFill) {
+  const baseAlpha = ctx.globalAlpha;
+  if (showFill && fillAlpha > 0.01) {
+    ctx.globalAlpha = baseAlpha * fillAlpha;
     const grad = ctx.createLinearGradient(0, pad.top, 0, h - pad.bottom);
     grad.addColorStop(0, palette.fillTop);
     grad.addColorStop(1, palette.fillBottom);
@@ -303,25 +350,48 @@ function renderCurve(ctx, layout, palette, pts, showFill) {
     ctx.fillStyle = grad;
     ctx.fill();
   }
+  ctx.globalAlpha = baseAlpha * lineAlpha;
   ctx.beginPath();
   ctx.moveTo(pts[0][0], pts[0][1]);
   drawSpline(ctx, pts);
-  ctx.strokeStyle = palette.line;
+  ctx.strokeStyle = strokeColor ?? palette.line;
   ctx.lineWidth = palette.lineWidth;
   ctx.lineJoin = "round";
   ctx.lineCap = "round";
   ctx.stroke();
+  ctx.globalAlpha = baseAlpha;
 }
-function drawLine(ctx, layout, palette, visible, smoothValue, now, showFill, scrubX, scrubAmount = 0) {
-  const { w, h, pad, toX, toY, chartW, chartH } = layout;
+function drawLine(ctx, layout, palette, visible, smoothValue, now, showFill, scrubX, scrubAmount = 0, chartReveal = 1, now_ms = 0) {
+  const { h, pad, toX, toY, chartW, chartH } = layout;
   const yMin = pad.top;
   const yMax = h - pad.bottom;
   const clampY = (y) => Math.max(yMin, Math.min(yMax, y));
-  const pts = visible.map(
-    (p, i) => i === visible.length - 1 ? [toX(p.time), clampY(toY(smoothValue))] : [toX(p.time), clampY(toY(p.value))]
-  );
-  pts.push([toX(now), clampY(toY(smoothValue))]);
+  const centerY = pad.top + chartH / 2;
+  const amplitude = chartH * LOADING_AMPLITUDE_RATIO;
+  const scroll = now_ms * LOADING_SCROLL_SPEED;
+  const morphY = chartReveal < 1 ? (rawY, x) => {
+    const t = Math.max(0, Math.min(1, (x - pad.left) / chartW));
+    const baseY = loadingY(t, centerY, amplitude, scroll);
+    return baseY + (rawY - baseY) * chartReveal;
+  } : (rawY, _x) => rawY;
+  const pts = visible.map((p, i) => {
+    const x = toX(p.time);
+    const y = i === visible.length - 1 ? morphY(clampY(toY(smoothValue)), x) : morphY(clampY(toY(p.value)), x);
+    return [x, y];
+  });
+  const liveTipX = toX(now);
+  const fullRightX = pad.left + chartW;
+  const tipX = chartReveal < 1 ? liveTipX + (fullRightX - liveTipX) * (1 - chartReveal) : liveTipX;
+  pts.push([tipX, morphY(clampY(toY(smoothValue)), tipX)]);
   if (pts.length < 2) return;
+  let lineAlpha = 1;
+  let fillAlpha = 1;
+  if (chartReveal < 1) {
+    const breath = loadingBreath(now_ms);
+    lineAlpha = breath + (1 - breath) * chartReveal;
+    fillAlpha = chartReveal;
+  }
+  const strokeColor = chartReveal < 1 ? blendColor(palette.gridLabel, palette.line, Math.min(1, chartReveal * 3)) : void 0;
   const isScrubbing = scrubX !== null;
   ctx.save();
   ctx.beginPath();
@@ -332,24 +402,26 @@ function drawLine(ctx, layout, palette, visible, smoothValue, now, showFill, scr
     ctx.beginPath();
     ctx.rect(0, 0, scrubX, h);
     ctx.clip();
-    renderCurve(ctx, layout, palette, pts, showFill);
+    renderCurve(ctx, layout, palette, pts, showFill, lineAlpha, fillAlpha, strokeColor);
     ctx.restore();
     ctx.save();
     ctx.beginPath();
     ctx.rect(scrubX, 0, layout.w - scrubX, h);
     ctx.clip();
     ctx.globalAlpha = 1 - scrubAmount * 0.6;
-    renderCurve(ctx, layout, palette, pts, showFill);
+    renderCurve(ctx, layout, palette, pts, showFill, lineAlpha, fillAlpha, strokeColor);
     ctx.restore();
   } else {
-    renderCurve(ctx, layout, palette, pts, showFill);
+    renderCurve(ctx, layout, palette, pts, showFill, lineAlpha, fillAlpha, strokeColor);
   }
   ctx.restore();
-  const currentY = Math.max(pad.top, Math.min(h - pad.bottom, toY(smoothValue)));
+  const realCurrentY = Math.max(pad.top, Math.min(h - pad.bottom, toY(smoothValue)));
+  const currentY = chartReveal < 1 ? centerY + (realCurrentY - centerY) * chartReveal : realCurrentY;
   ctx.setLineDash([4, 4]);
   ctx.strokeStyle = palette.dashLine;
   ctx.lineWidth = 1;
-  if (isScrubbing) ctx.globalAlpha = 1 - scrubAmount * 0.2;
+  const dashBase = isScrubbing ? 1 - scrubAmount * 0.2 : 1;
+  ctx.globalAlpha = chartReveal < 1 ? dashBase * chartReveal : dashBase;
   ctx.beginPath();
   ctx.moveTo(pad.left, currentY);
   ctx.lineTo(layout.w - pad.right, currentY);
@@ -364,27 +436,17 @@ function drawLine(ctx, layout, palette, visible, smoothValue, now, showFill, scr
 // src/draw/dot.ts
 var PULSE_INTERVAL = 1500;
 var PULSE_DURATION = 900;
-function parseColor(color) {
-  const hex = color.match(/^#([0-9a-f]{3,8})$/i);
-  if (hex) {
-    let h = hex[1];
-    if (h.length === 3) h = h[0] + h[0] + h[1] + h[1] + h[2] + h[2];
-    return [parseInt(h.slice(0, 2), 16), parseInt(h.slice(2, 4), 16), parseInt(h.slice(4, 6), 16)];
-  }
-  const rgb = color.match(/rgba?\(\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)/);
-  if (rgb) return [+rgb[1], +rgb[2], +rgb[3]];
-  return null;
-}
 function lerpColor(a, b, t) {
   const r = Math.round(a[0] + (b[0] - a[0]) * t);
   const g = Math.round(a[1] + (b[1] - a[1]) * t);
   const bl = Math.round(a[2] + (b[2] - a[2]) * t);
   return `rgb(${r},${g},${bl})`;
 }
-function drawDot(ctx, x, y, palette, pulse = true, scrubAmount = 0) {
+function drawDot(ctx, x, y, palette, pulse = true, scrubAmount = 0, now_ms = performance.now()) {
+  const baseAlpha = ctx.globalAlpha;
   const dim = scrubAmount * 0.7;
   if (pulse && dim < 0.3) {
-    const t = Date.now() % PULSE_INTERVAL / PULSE_DURATION;
+    const t = now_ms % PULSE_INTERVAL / PULSE_DURATION;
     if (t < 1) {
       const radius = 9 + t * 12;
       const pulseAlpha = 0.35 * (1 - t) * (1 - dim * 3);
@@ -392,13 +454,13 @@ function drawDot(ctx, x, y, palette, pulse = true, scrubAmount = 0) {
       ctx.arc(x, y, radius, 0, Math.PI * 2);
       ctx.strokeStyle = palette.line;
       ctx.lineWidth = 1.5;
-      ctx.globalAlpha = pulseAlpha;
+      ctx.globalAlpha = baseAlpha * pulseAlpha;
       ctx.stroke();
     }
   }
-  const outerRgb = parseColor(palette.badgeOuterBg) ?? [255, 255, 255];
+  const outerRgb = parseColorRgb(palette.badgeOuterBg);
   ctx.save();
-  ctx.globalAlpha = 1;
+  ctx.globalAlpha = baseAlpha;
   ctx.shadowColor = palette.badgeOuterShadow;
   ctx.shadowBlur = 6 * (1 - dim);
   ctx.shadowOffsetY = 1;
@@ -407,18 +469,19 @@ function drawDot(ctx, x, y, palette, pulse = true, scrubAmount = 0) {
   ctx.fillStyle = palette.badgeOuterBg;
   ctx.fill();
   ctx.restore();
-  ctx.globalAlpha = 1;
+  ctx.globalAlpha = baseAlpha;
   ctx.beginPath();
   ctx.arc(x, y, 3.5, 0, Math.PI * 2);
   if (dim > 0.01) {
-    const lineRgb = parseColor(palette.line) ?? [100, 100, 255];
+    const lineRgb = parseColorRgb(palette.line);
     ctx.fillStyle = lerpColor(lineRgb, outerRgb, dim);
   } else {
     ctx.fillStyle = palette.line;
   }
   ctx.fill();
 }
-function drawArrows(ctx, x, y, momentum, palette, arrows, dt) {
+function drawArrows(ctx, x, y, momentum, palette, arrows, dt, now_ms = performance.now()) {
+  const baseAlpha = ctx.globalAlpha;
   const upTarget = momentum === "up" ? 1 : 0;
   const downTarget = momentum === "down" ? 1 : 0;
   const canFadeInUp = arrows.down < 0.02;
@@ -429,7 +492,7 @@ function drawArrows(ctx, x, y, momentum, palette, arrows, dt) {
   if (arrows.down < 0.01) arrows.down = 0;
   if (arrows.up > 0.99) arrows.up = 1;
   if (arrows.down > 0.99) arrows.down = 1;
-  const cycle = Date.now() % 1400 / 1400;
+  const cycle = now_ms % 1400 / 1400;
   const drawChevrons = (dir, opacity) => {
     if (opacity < 0.01) return;
     const baseX = x + 19;
@@ -445,7 +508,7 @@ function drawArrows(ctx, x, y, momentum, palette, arrows, dt) {
       const localT = cycle - start;
       const wave = localT >= 0 && localT < dur ? Math.sin(localT / dur * Math.PI) : 0;
       const pulse = 0.3 + 0.7 * wave;
-      ctx.globalAlpha = opacity * pulse;
+      ctx.globalAlpha = baseAlpha * opacity * pulse;
       const nudge = dir === -1 ? -3 : 3;
       const cy = baseY + dir * (i * 8 - 4) + nudge;
       ctx.beginPath();
@@ -458,13 +521,13 @@ function drawArrows(ctx, x, y, momentum, palette, arrows, dt) {
   };
   drawChevrons(-1, arrows.up);
   drawChevrons(1, arrows.down);
-  ctx.globalAlpha = 1;
+  ctx.globalAlpha = baseAlpha;
 }
 
 // src/draw/crosshair.ts
 function drawCrosshair(ctx, layout, palette, hoverX, hoverValue, hoverTime, formatValue, formatTime, scrubOpacity, tooltipY, liveDotX, tooltipOutline) {
   if (scrubOpacity < 0.01) return;
-  const { w, h, pad, toY } = layout;
+  const { h, pad, toY } = layout;
   const y = toY(hoverValue);
   ctx.save();
   ctx.globalAlpha = scrubOpacity * 0.5;
@@ -496,7 +559,7 @@ function drawCrosshair(ctx, layout, palette, hoverX, hoverValue, hoverTime, form
   const totalW = valueW + sepW + timeW;
   let tx = hoverX - totalW / 2;
   const minX = pad.left + 4;
-  const dotRightEdge = liveDotX != null ? liveDotX + 7 : w - pad.right;
+  const dotRightEdge = liveDotX != null ? liveDotX + 7 : layout.w - pad.right;
   const maxX = dotRightEdge - totalW;
   if (tx < minX) tx = minX;
   if (tx > maxX) tx = maxX;
@@ -571,7 +634,7 @@ function niceTimeInterval(windowSecs) {
 
 // src/draw/timeAxis.ts
 var FADE = 0.08;
-function drawTimeAxis(ctx, layout, palette, windowSecs, _targetWindowSecs, formatTime, state, dt) {
+function drawTimeAxis(ctx, layout, palette, windowSecs, targetWindowSecs, formatTime, state, dt) {
   const { h, pad, leftEdge, rightEdge, toX } = layout;
   const chartLeft = pad.left;
   const chartRight = layout.w - pad.right;
@@ -586,9 +649,9 @@ function drawTimeAxis(ctx, layout, palette, windowSecs, _targetWindowSecs, forma
     return fromEdge / fadeZone;
   };
   ctx.font = palette.labelFont;
-  const targetPxPerSec = chartW / _targetWindowSecs;
-  let interval = niceTimeInterval(_targetWindowSecs);
-  while (interval * targetPxPerSec < 60 && interval < _targetWindowSecs) {
+  const targetPxPerSec = chartW / targetWindowSecs;
+  let interval = niceTimeInterval(targetWindowSecs);
+  while (interval * targetPxPerSec < 60 && interval < targetWindowSecs) {
     interval *= 2;
   }
   const useLocalDays = interval >= 86400;
@@ -625,6 +688,7 @@ function drawTimeAxis(ctx, layout, palette, windowSecs, _targetWindowSecs, forma
       label.alpha = next;
     }
   }
+  const baseAlpha = ctx.globalAlpha;
   const lineY = h - pad.bottom;
   const tickLen = 5;
   ctx.strokeStyle = palette.gridLine;
@@ -660,7 +724,7 @@ function drawTimeAxis(ctx, layout, palette, windowSecs, _targetWindowSecs, forma
   }
   for (const label of drawn) {
     ctx.save();
-    ctx.globalAlpha = label.alpha;
+    ctx.globalAlpha = baseAlpha * label.alpha;
     ctx.strokeStyle = palette.gridLine;
     ctx.lineWidth = 1;
     ctx.beginPath();
@@ -781,11 +845,12 @@ function drawOrderbook(ctx, layout, palette, orderbook, dt, state, swingMagnitud
     state.labels[writeIdx++] = l;
   }
   state.labels.length = writeIdx;
+  const baseAlpha = ctx.globalAlpha;
   ctx.save();
   ctx.font = '600 13px "SF Mono", Menlo, monospace';
   ctx.textAlign = "left";
   ctx.textBaseline = "middle";
-  ctx.globalAlpha = 1;
+  ctx.globalAlpha = baseAlpha;
   const outlineColor = `rgb(${bg[0]},${bg[1]},${bg[2]})`;
   for (let i = 0; i < state.labels.length; i++) {
     const l = state.labels[i];
@@ -902,18 +967,44 @@ function drawFrame(ctx, layout, palette, opts) {
     shake.amplitude *= decayRate;
     if (shake.amplitude < SHAKE_MIN_AMPLITUDE) shake.amplitude = 0;
   }
-  if (opts.referenceLine) {
+  const reveal = opts.chartReveal;
+  const pause = opts.pauseProgress;
+  const revealRamp = (start, end) => {
+    const t = Math.max(0, Math.min(1, (reveal - start) / (end - start)));
+    return t * t * (3 - 2 * t);
+  };
+  if (opts.referenceLine && reveal > 0.01) {
+    ctx.save();
+    if (reveal < 1) ctx.globalAlpha = reveal;
     drawReferenceLine(ctx, layout, palette, opts.referenceLine);
+    ctx.restore();
   }
   if (opts.showGrid) {
-    drawGrid(ctx, layout, palette, opts.formatValue, opts.gridState, opts.dt);
+    const gridAlpha = reveal < 1 ? revealRamp(0.15, 0.7) : 1;
+    if (gridAlpha > 0.01) {
+      ctx.save();
+      if (gridAlpha < 1) ctx.globalAlpha = gridAlpha;
+      drawGrid(ctx, layout, palette, opts.formatValue, opts.gridState, opts.dt);
+      ctx.restore();
+    }
   }
-  if (opts.orderbookData && opts.orderbookState) {
+  if (opts.orderbookData && opts.orderbookState && reveal > 0.01) {
+    ctx.save();
+    if (reveal < 1) ctx.globalAlpha = reveal;
     drawOrderbook(ctx, layout, palette, opts.orderbookData, opts.dt, opts.orderbookState, opts.swingMagnitude);
+    ctx.restore();
   }
   const scrubX = opts.scrubAmount > 0.05 ? opts.hoverX : null;
-  const pts = drawLine(ctx, layout, palette, opts.visible, opts.smoothValue, opts.now, opts.showFill, scrubX, opts.scrubAmount);
-  drawTimeAxis(ctx, layout, palette, opts.windowSecs, opts.targetWindowSecs, opts.formatTime, opts.timeAxisState, opts.dt);
+  const pts = drawLine(ctx, layout, palette, opts.visible, opts.smoothValue, opts.now, opts.showFill, scrubX, opts.scrubAmount, reveal, opts.now_ms);
+  {
+    const timeAlpha = reveal < 1 ? revealRamp(0.15, 0.7) : 1;
+    if (timeAlpha > 0.01) {
+      ctx.save();
+      if (timeAlpha < 1) ctx.globalAlpha = timeAlpha;
+      drawTimeAxis(ctx, layout, palette, opts.windowSecs, opts.targetWindowSecs, opts.formatTime, opts.timeAxisState, opts.dt);
+      ctx.restore();
+    }
+  }
   if (pts && pts.length > 0) {
     const lastPt = pts[pts.length - 1];
     let dotScrub = opts.scrubAmount;
@@ -922,19 +1013,34 @@ function drawFrame(ctx, layout, palette, opts) {
       const fadeStart = Math.min(80, layout.chartW * 0.3);
       dotScrub = distToLive < CROSSHAIR_FADE_MIN_PX ? 0 : distToLive >= fadeStart ? opts.scrubAmount : (distToLive - CROSSHAIR_FADE_MIN_PX) / (fadeStart - CROSSHAIR_FADE_MIN_PX) * opts.scrubAmount;
     }
-    drawDot(ctx, lastPt[0], lastPt[1], palette, opts.showPulse, dotScrub);
+    const dotAlpha = reveal < 0.3 ? 0 : (reveal - 0.3) / 0.7;
+    const showPulse = opts.showPulse && reveal > 0.6 && pause < 0.5;
+    if (dotAlpha > 0.01) {
+      ctx.save();
+      if (dotAlpha < 1) ctx.globalAlpha = dotAlpha;
+      drawDot(ctx, lastPt[0], lastPt[1], palette, showPulse, dotScrub, opts.now_ms);
+      ctx.restore();
+    }
     if (opts.showMomentum) {
-      drawArrows(
-        ctx,
-        lastPt[0],
-        lastPt[1],
-        opts.momentum,
-        palette,
-        opts.arrowState,
-        opts.dt
-      );
+      const arrowReveal = reveal < 1 ? revealRamp(0.6, 1) : 1;
+      const arrowAlpha = arrowReveal * (1 - pause);
+      if (arrowAlpha > 0.01) {
+        ctx.save();
+        if (arrowAlpha < 1) ctx.globalAlpha = arrowAlpha;
+        drawArrows(
+          ctx,
+          lastPt[0],
+          lastPt[1],
+          opts.momentum,
+          palette,
+          opts.arrowState,
+          opts.dt,
+          opts.now_ms
+        );
+        ctx.restore();
+      }
     }
-    if (opts.particleState) {
+    if (opts.particleState && reveal > 0.9) {
       const burstIntensity = spawnOnSwing(
         opts.particleState,
         opts.momentum,
@@ -988,6 +1094,92 @@ function drawFrame(ctx, layout, palette, opts) {
   }
 }
 
+// src/draw/loading.ts
+function drawLoading(ctx, w, h, pad, palette, now_ms, alpha = 1) {
+  const chartW = w - pad.left - pad.right;
+  const chartH = h - pad.top - pad.bottom;
+  const centerY = pad.top + chartH / 2;
+  const leftX = pad.left;
+  const amplitude = chartH * LOADING_AMPLITUDE_RATIO;
+  const scroll = now_ms * LOADING_SCROLL_SPEED;
+  const breath = loadingBreath(now_ms);
+  const numPts = 32;
+  const pts = [];
+  for (let i = 0; i <= numPts; i++) {
+    const t = i / numPts;
+    const x = leftX + t * chartW;
+    const y = loadingY(t, centerY, amplitude, scroll);
+    pts.push([x, y]);
+  }
+  ctx.beginPath();
+  ctx.moveTo(pts[0][0], pts[0][1]);
+  drawSpline(ctx, pts);
+  ctx.strokeStyle = palette.line;
+  ctx.lineWidth = palette.lineWidth;
+  ctx.globalAlpha = breath * alpha;
+  ctx.lineCap = "round";
+  ctx.lineJoin = "round";
+  ctx.stroke();
+  ctx.globalAlpha = 1;
+}
+
+// src/draw/empty.ts
+function drawEmpty(ctx, w, h, pad, palette, alpha = 1, now_ms = 0, skipLine = false, emptyText) {
+  const chartW = w - pad.left - pad.right;
+  const chartH = h - pad.top - pad.bottom;
+  const centerY = pad.top + chartH / 2;
+  const cx = pad.left + chartW / 2;
+  const text = emptyText ?? "No data to display";
+  ctx.font = "400 12px system-ui, -apple-system, sans-serif";
+  const amplitude = chartH * LOADING_AMPLITUDE_RATIO;
+  const textW = ctx.measureText(text).width;
+  const gapHalf = textW / 2 + 20;
+  const fadeW = 30;
+  if (!skipLine) {
+    const scroll = now_ms * LOADING_SCROLL_SPEED;
+    const breath = loadingBreath(now_ms);
+    const numPts = 32;
+    const pts = [];
+    for (let i = 0; i <= numPts; i++) {
+      const t = i / numPts;
+      const x = pad.left + t * chartW;
+      const y = loadingY(t, centerY, amplitude, scroll);
+      pts.push([x, y]);
+    }
+    ctx.beginPath();
+    ctx.moveTo(pts[0][0], pts[0][1]);
+    drawSpline(ctx, pts);
+    ctx.strokeStyle = palette.gridLabel;
+    ctx.lineWidth = palette.lineWidth;
+    ctx.globalAlpha = breath * alpha;
+    ctx.lineCap = "round";
+    ctx.lineJoin = "round";
+    ctx.stroke();
+  }
+  ctx.save();
+  ctx.globalCompositeOperation = "destination-out";
+  const gapLeft = cx - gapHalf - fadeW;
+  const gapRight = cx + gapHalf + fadeW;
+  const eraseGrad = ctx.createLinearGradient(gapLeft, 0, gapRight, 0);
+  eraseGrad.addColorStop(0, "rgba(0,0,0,0)");
+  eraseGrad.addColorStop(fadeW / (gapRight - gapLeft), "rgba(0,0,0,1)");
+  eraseGrad.addColorStop(1 - fadeW / (gapRight - gapLeft), "rgba(0,0,0,1)");
+  eraseGrad.addColorStop(1, "rgba(0,0,0,0)");
+  ctx.fillStyle = eraseGrad;
+  ctx.globalAlpha = alpha;
+  const eraseH = amplitude * 2 + palette.lineWidth + 6;
+  ctx.fillRect(gapLeft, centerY - eraseH / 2, gapRight - gapLeft, eraseH);
+  ctx.restore();
+  ctx.textAlign = "center";
+  ctx.textBaseline = "middle";
+  ctx.globalAlpha = 0.35 * alpha;
+  ctx.fillStyle = palette.gridLabel;
+  ctx.fillText(text, cx, centerY);
+  ctx.globalAlpha = 1;
+  ctx.textAlign = "start";
+  ctx.textBaseline = "alphabetic";
+}
+
 // src/draw/badge.ts
 function badgeSvgPath(pillW, pillH, tailLen, tailSpread) {
   const r = pillH / 2;
@@ -1034,6 +1226,11 @@ var VALUE_SNAP_THRESHOLD = 1e-3;
 var ADAPTIVE_SPEED_BOOST = 0.2;
 var MOMENTUM_GREEN = [34, 197, 94];
 var MOMENTUM_RED = [239, 68, 68];
+var CHART_REVEAL_SPEED = 0.14;
+var PAUSE_PROGRESS_SPEED = 0.12;
+var PAUSE_CATCHUP_SPEED = 0.08;
+var PAUSE_CATCHUP_SPEED_FAST = 0.22;
+var LOADING_ALPHA_SPEED = 0.14;
 function computeAdaptiveSpeed(value, displayValue, displayMin, displayMax, lerpSpeed, noMotion) {
   const valGap = Math.abs(value - displayValue);
   const prevRange = displayMax - displayMin || 1;
@@ -1165,12 +1362,14 @@ function updateHoverState(hoverPixelX, pad, w, layout, now, visible, scrubAmount
     lastHover
   };
 }
-function updateBadgeDOM(badge, cfg, smoothValue, layout, momentum, badgeY, badgeColor, isWindowTransitioning, noMotion, ctx, dt) {
-  if (!cfg.showBadge) {
+function updateBadgeDOM(badge, cfg, smoothValue, layout, momentum, badgeY, badgeColor, isWindowTransitioning, noMotion, ctx, dt, chartReveal = 1) {
+  if (!cfg.showBadge || chartReveal < 0.25) {
     badge.container.style.display = "none";
     return badgeY;
   }
   badge.container.style.display = "";
+  const badgeOpacity = chartReveal < 0.5 ? (chartReveal - 0.25) / 0.25 : 1;
+  badge.container.style.opacity = badgeOpacity < 1 ? String(badgeOpacity) : "";
   const { w, h, pad } = layout;
   const text = cfg.formatValue(smoothValue);
   badge.text.textContent = text;
@@ -1193,7 +1392,9 @@ function updateBadgeDOM(badge, cfg, smoothValue, layout, momentum, badgeY, badge
   badge.svg.setAttribute("height", String(pillH));
   badge.svg.setAttribute("viewBox", `0 0 ${totalW} ${pillH}`);
   badge.path.setAttribute("d", cfg.badgeTail ? badgeSvgPath(pillW, pillH, BADGE_TAIL_LEN, BADGE_TAIL_SPREAD) : badgePillOnly(pillW, pillH));
-  const targetBadgeY = Math.max(pad.top, Math.min(h - pad.bottom, layout.toY(smoothValue)));
+  const centerY = pad.top + layout.chartH / 2;
+  const realTargetY = Math.max(pad.top, Math.min(h - pad.bottom, layout.toY(smoothValue)));
+  const targetBadgeY = chartReveal < 1 ? centerY + (realTargetY - centerY) * chartReveal : realTargetY;
   if (badgeY === null || noMotion) {
     badgeY = targetBadgeY;
   } else {
@@ -1258,12 +1459,20 @@ function useLivelineEngine(canvasRef, containerRef, config) {
   const badgeYRef = useRef(null);
   const reducedMotionRef = useRef(false);
   const sizeRef = useRef({ w: 0, h: 0 });
+  const ctxRef = useRef(null);
   const rafRef = useRef(0);
   const lastFrameRef = useRef(0);
   const badgeRef = useRef(null);
   const hoverXRef = useRef(null);
   const scrubAmountRef = useRef(0);
   const lastHoverRef = useRef(null);
+  const chartRevealRef = useRef(0);
+  const pauseProgressRef = useRef(0);
+  const timeDebtRef = useRef(0);
+  const lastDataRef = useRef([]);
+  const frozenNowRef = useRef(0);
+  const pausedDataRef = useRef(null);
+  const loadingAlphaRef = useRef(config.loading ? 1 : 0);
   useEffect(() => {
     const container = containerRef.current;
     if (!container) return;
@@ -1384,19 +1593,75 @@ function useLivelineEngine(canvasRef, containerRef, config) {
       canvas.style.width = `${w}px`;
       canvas.style.height = `${h}px`;
     }
-    const ctx = canvas.getContext("2d");
+    let ctx = ctxRef.current;
+    if (!ctx || ctx.canvas !== canvas) {
+      ctx = canvas.getContext("2d");
+      ctxRef.current = ctx;
+    }
     if (!ctx) {
       rafRef.current = requestAnimationFrame(draw);
       return;
     }
     applyDpr(ctx, dpr, w, h);
     const noMotion = reducedMotionRef.current;
-    const points = cfg.data;
-    if (points.length < 2) {
+    if (cfg.paused && pausedDataRef.current === null && cfg.data.length >= 2) {
+      pausedDataRef.current = cfg.data.slice();
+    }
+    if (!cfg.paused) {
+      pausedDataRef.current = null;
+    }
+    const points = pausedDataRef.current ?? cfg.data;
+    const hasData = points.length >= 2;
+    const pad = cfg.padding;
+    const chartH = h - pad.top - pad.bottom;
+    const pauseTarget = cfg.paused ? 1 : 0;
+    pauseProgressRef.current = noMotion ? pauseTarget : lerp(pauseProgressRef.current, pauseTarget, PAUSE_PROGRESS_SPEED, dt);
+    if (pauseProgressRef.current < 5e-3) pauseProgressRef.current = 0;
+    if (pauseProgressRef.current > 0.995) pauseProgressRef.current = 1;
+    const pauseProgress = pauseProgressRef.current;
+    const pausedDt = dt * (1 - pauseProgress);
+    const realDtSec = dt / 1e3;
+    timeDebtRef.current += realDtSec * pauseProgress;
+    if (!cfg.paused && timeDebtRef.current > 1e-3) {
+      const catchUpSpeed = timeDebtRef.current > 10 ? PAUSE_CATCHUP_SPEED_FAST : PAUSE_CATCHUP_SPEED;
+      timeDebtRef.current = lerp(timeDebtRef.current, 0, catchUpSpeed, dt);
+      if (timeDebtRef.current < 0.01) timeDebtRef.current = 0;
+    }
+    const loadingTarget = cfg.loading ? 1 : 0;
+    loadingAlphaRef.current = noMotion ? loadingTarget : lerp(loadingAlphaRef.current, loadingTarget, LOADING_ALPHA_SPEED, dt);
+    if (loadingAlphaRef.current < 0.01) loadingAlphaRef.current = 0;
+    if (loadingAlphaRef.current > 0.99) loadingAlphaRef.current = 1;
+    const loadingAlpha = loadingAlphaRef.current;
+    const revealTarget = !cfg.loading && hasData ? 1 : 0;
+    chartRevealRef.current = noMotion ? revealTarget : lerp(chartRevealRef.current, revealTarget, CHART_REVEAL_SPEED, dt);
+    if (Math.abs(chartRevealRef.current - revealTarget) < 5e-3) {
+      chartRevealRef.current = revealTarget;
+    }
+    const chartReveal = chartRevealRef.current;
+    const useStash = !hasData && chartReveal > 5e-3 && lastDataRef.current.length >= 2;
+    if (hasData) {
+      lastDataRef.current = points;
+    }
+    if (!hasData && !useStash) {
+      if (loadingAlpha > 0.01) {
+        drawLoading(ctx, w, h, pad, cfg.palette, now_ms, loadingAlpha);
+      }
+      if (1 - loadingAlpha > 0.01) {
+        drawEmpty(ctx, w, h, pad, cfg.palette, 1 - loadingAlpha, now_ms, false, cfg.emptyText);
+      }
+      ctx.save();
+      ctx.globalCompositeOperation = "destination-out";
+      const fadeGrad = ctx.createLinearGradient(pad.left, 0, pad.left + FADE_EDGE_WIDTH, 0);
+      fadeGrad.addColorStop(0, "rgba(0, 0, 0, 1)");
+      fadeGrad.addColorStop(1, "rgba(0, 0, 0, 0)");
+      ctx.fillStyle = fadeGrad;
+      ctx.fillRect(0, 0, pad.left + FADE_EDGE_WIDTH, h);
+      ctx.restore();
       if (badgeRef.current) badgeRef.current.container.style.display = "none";
       rafRef.current = requestAnimationFrame(draw);
       return;
     }
+    const effectivePoints = useStash ? lastDataRef.current : points;
     const adaptiveSpeed = computeAdaptiveSpeed(
       cfg.value,
       displayValueRef.current,
@@ -1405,18 +1670,22 @@ function useLivelineEngine(canvasRef, containerRef, config) {
       cfg.lerpSpeed,
       noMotion
     );
-    displayValueRef.current = lerp(displayValueRef.current, cfg.value, adaptiveSpeed, dt);
-    const prevRange = displayMaxRef.current - displayMinRef.current || 1;
-    if (Math.abs(displayValueRef.current - cfg.value) < prevRange * VALUE_SNAP_THRESHOLD) {
-      displayValueRef.current = cfg.value;
+    if (!useStash) {
+      displayValueRef.current = lerp(displayValueRef.current, cfg.value, adaptiveSpeed, pausedDt);
+      if (pauseProgress < 0.5) {
+        const prevRange = displayMaxRef.current - displayMinRef.current || 1;
+        if (Math.abs(displayValueRef.current - cfg.value) < prevRange * VALUE_SNAP_THRESHOLD) {
+          displayValueRef.current = cfg.value;
+        }
+      }
     }
     const smoothValue = displayValueRef.current;
-    const pad = cfg.padding;
     const chartW = w - pad.left - pad.right;
     const needsArrowRoom = cfg.showMomentum;
     const buffer = needsArrowRoom ? Math.max(WINDOW_BUFFER, 37 / Math.max(chartW, 1)) : WINDOW_BUFFER;
     const transition = windowTransitionRef.current;
-    const now = Date.now() / 1e3;
+    if (hasData) frozenNowRef.current = Date.now() / 1e3 - timeDebtRef.current;
+    const now = useStash ? frozenNowRef.current : Date.now() / 1e3 - timeDebtRef.current;
     const windowResult = updateWindowTransition(
       cfg,
       transition,
@@ -1426,7 +1695,7 @@ function useLivelineEngine(canvasRef, containerRef, config) {
       noMotion,
       now_ms,
       now,
-      points,
+      effectivePoints,
       smoothValue,
       buffer
     );
@@ -1435,9 +1704,10 @@ function useLivelineEngine(canvasRef, containerRef, config) {
     const windowTransProgress = windowResult.windowTransProgress;
     const rightEdge = now + windowSecs * buffer;
     const leftEdge = rightEdge - windowSecs;
+    const filterRight = rightEdge - (rightEdge - now) * pauseProgress;
     const visible = [];
-    for (const p of points) {
-      if (p.time >= leftEdge - 2 && p.time <= rightEdge) {
+    for (const p of effectivePoints) {
+      if (p.time >= leftEdge - 2 && p.time <= filterRight) {
         visible.push(p);
       }
     }
@@ -1446,7 +1716,6 @@ function useLivelineEngine(canvasRef, containerRef, config) {
       rafRef.current = requestAnimationFrame(draw);
       return;
     }
-    const chartH = h - pad.top - pad.bottom;
     const computedRange = computeRange(visible, smoothValue, cfg.referenceLine?.value, cfg.exaggerate);
     const isWindowTransitioning = transition.startMs > 0;
     const rangeResult = updateRange(
@@ -1461,7 +1730,7 @@ function useLivelineEngine(canvasRef, containerRef, config) {
       transition,
       adaptiveSpeed,
       chartH,
-      dt
+      pausedDt
     );
     rangeInitedRef.current = rangeResult.rangeInited;
     targetMinRef.current = rangeResult.targetMin;
@@ -1535,8 +1804,18 @@ function useLivelineEngine(canvasRef, containerRef, config) {
       particleState: cfg.degenOptions ? particleStateRef.current : void 0,
       particleOptions: cfg.degenOptions,
       swingMagnitude,
-      shakeState: cfg.degenOptions ? shakeStateRef.current : void 0
+      shakeState: cfg.degenOptions ? shakeStateRef.current : void 0,
+      chartReveal,
+      pauseProgress,
+      now_ms
     });
+    const bgAlpha = 1 - chartReveal;
+    if (bgAlpha > 0.01 && revealTarget === 0 && !cfg.loading) {
+      const bgEmptyAlpha = (1 - loadingAlpha) * bgAlpha;
+      if (bgEmptyAlpha > 0.01) {
+        drawEmpty(ctx, w, h, pad, cfg.palette, bgEmptyAlpha, now_ms, true, cfg.emptyText);
+      }
+    }
     const badge = badgeRef.current;
     if (badge) {
       badgeYRef.current = updateBadgeDOM(
@@ -1550,8 +1829,13 @@ function useLivelineEngine(canvasRef, containerRef, config) {
         isWindowTransitioning,
         noMotion,
         ctx,
-        dt
+        pausedDt,
+        chartReveal
       );
+      if (pauseProgress > 0.01 && badge.container.style.display !== "none") {
+        const base = badge.container.style.opacity ? parseFloat(badge.container.style.opacity) : 1;
+        badge.container.style.opacity = String(base * (1 - pauseProgress));
+      }
     }
     const valEl = cfg.valueDisplayRef?.current;
     if (valEl) {
@@ -1592,6 +1876,9 @@ function Liveline({
   momentum = true,
   fill = true,
   scrub = true,
+  loading = false,
+  paused = false,
+  emptyText,
   exaggerate = false,
   degen: degenProp,
   badgeTail = true,
@@ -1621,7 +1908,7 @@ function Liveline({
   const windowBarRef = useRef2(null);
   const windowBtnRefs = useRef2(/* @__PURE__ */ new Map());
   const [indicatorStyle, setIndicatorStyle] = useState(null);
-  const palette = resolveTheme(color, theme);
+  const palette = useMemo(() => resolveTheme(color, theme), [color, theme]);
   const isDark = theme === "dark";
   const showMomentum = momentum !== false;
   const momentumOverride = typeof momentum === "string" ? momentum : void 0;
@@ -1677,7 +1964,10 @@ function Liveline({
     tooltipOutline,
     valueMomentumColor,
     valueDisplayRef: showValue ? valueDisplayRef : void 0,
-    orderbookData: orderbook
+    orderbookData: orderbook,
+    loading,
+    paused,
+    emptyText
   });
   const cursorStyle = scrub ? cursor : "default";
   return /* @__PURE__ */ jsxs(Fragment, { children: [