@sarmal/core 0.26.0 → 0.27.0

package/dist/terminal.js

@@ -0,0 +1,585 @@
+// src/engine.ts
+var TWO_PI = Math.PI * 2;
+var POINTS_PER_PERIOD_UNIT = 50;
+function lerp(start, end, t) {
+  return start + (end - start) * t;
+}
+var EMPTY_PARAMS = {};
+var CircularBuffer = class {
+  constructor(capacity) {
+    this.head = 0;
+    this.count = 0;
+    this.capacity = capacity;
+    this.data = Array.from({ length: capacity }, () => ({ x: 0, y: 0 }));
+    this.result = Array.from({ length: capacity }, () => ({ x: 0, y: 0 }));
+  }
+  /** Mutates in-place */
+  push(x, y) {
+    const slot = this.data[this.head];
+    slot.x = x;
+    slot.y = y;
+    this.head = (this.head + 1) % this.capacity;
+    if (this.count < this.capacity) {
+      this.count++;
+    }
+  }
+  /**
+   * Copies ordered points into the pre-allocated result buffer and returns it
+   * Note: The *same* array reference is returned every call,
+   *  so `result.length` is also always `capacity`
+   */
+  toArray() {
+    const start = this.count < this.capacity ? 0 : this.head;
+    for (let i = 0; i < this.count; i++) {
+      const src = this.data[(start + i) % this.capacity];
+      const dst = this.result[i];
+      dst.x = src.x;
+      dst.y = src.y;
+    }
+    return this.result;
+  }
+  clear() {
+    this.head = 0;
+    this.count = 0;
+  }
+  get length() {
+    return this.count;
+  }
+};
+function resolveCurve(curveDef) {
+  const period = curveDef.period ?? TWO_PI;
+  if (!Number.isFinite(period) || period <= 0) {
+    throw new RangeError(`[sarmal] period must be a positive finite number, got ${period}`);
+  }
+  const speed = curveDef.speed ?? 1;
+  if (!Number.isFinite(speed)) {
+    throw new RangeError(`[sarmal] speed must be a finite number, got ${speed}`);
+  }
+  return {
+    name: curveDef.name,
+    fn: curveDef.fn,
+    period,
+    speed,
+    skeleton: curveDef.skeleton,
+    skeletonFn: curveDef.skeletonFn,
+  };
+}
+function createEngine(curveDef, trailLength = 120) {
+  if (!Number.isFinite(trailLength) || trailLength <= 0) {
+    throw new RangeError(
+      `[sarmal] trailLength must be a positive finite number, got ${trailLength}`,
+    );
+  }
+  let curve = resolveCurve(curveDef);
+  const trail = new CircularBuffer(trailLength);
+  let phase = 0;
+  let actualTime = 0;
+  let userSpeedOverride = null;
+  let morphCurveB = null;
+  let _morphAlpha = null;
+  let _morphStrategy = "normalized";
+  let _speedTransition = null;
+  function sampleSkeleton(c, samplePhase) {
+    if (c.skeletonFn) {
+      return c.skeletonFn(samplePhase);
+    }
+    if (c.skeleton === "live") {
+      return c.fn(samplePhase, actualTime, EMPTY_PARAMS);
+    }
+    return c.fn(samplePhase, 0, EMPTY_PARAMS);
+  }
+  return {
+    tick(deltaTime) {
+      if (_speedTransition !== null) {
+        _speedTransition.elapsed += deltaTime * 1e3;
+        const alpha = Math.min(_speedTransition.elapsed / _speedTransition.duration, 1);
+        userSpeedOverride = lerp(_speedTransition.from, _speedTransition.to, alpha);
+        if (alpha >= 1) {
+          userSpeedOverride = _speedTransition.to;
+          _speedTransition.resolve();
+          _speedTransition = null;
+        }
+      }
+      let effectiveSpeed = userSpeedOverride ?? curve.speed;
+      if (morphCurveB !== null && _morphAlpha !== null) {
+        effectiveSpeed = lerp(effectiveSpeed, morphCurveB.speed, _morphAlpha);
+      }
+      phase = (phase + effectiveSpeed * deltaTime) % curve.period;
+      actualTime += deltaTime;
+      if (morphCurveB !== null && _morphAlpha !== null) {
+        const a = curve.fn(phase, actualTime, EMPTY_PARAMS);
+        const phaseB =
+          _morphStrategy === "normalized" ? (phase / curve.period) * morphCurveB.period : phase;
+        const b = morphCurveB.fn(phaseB, actualTime, EMPTY_PARAMS);
+        trail.push(a.x + (b.x - a.x) * _morphAlpha, a.y + (b.y - a.y) * _morphAlpha);
+      } else {
+        const point = curve.fn(phase, actualTime, EMPTY_PARAMS);
+        trail.push(point.x, point.y);
+      }
+      return trail.toArray();
+    },
+    get trailCount() {
+      return trail.length;
+    },
+    get trailLength() {
+      return trailLength;
+    },
+    get isLiveSkeleton() {
+      return curve.skeleton === "live";
+    },
+    get morphAlpha() {
+      return _morphAlpha;
+    },
+    reset() {
+      phase = 0;
+      actualTime = 0;
+      trail.clear();
+    },
+    jump(newPhase, { clearTrail = false } = {}) {
+      phase = ((newPhase % curve.period) + curve.period) % curve.period;
+      if (clearTrail) {
+        trail.clear();
+      }
+    },
+    seek(targetPhase, { wrap = false, step = curve.period / trailLength } = {}) {
+      const advance = curve.speed * step;
+      const target = ((targetPhase % curve.period) + curve.period) % curve.period;
+      const targetTime = target / curve.speed;
+      phase = target;
+      actualTime = targetTime;
+      trail.clear();
+      const pointsFromStart = Math.floor(target / advance) + 1;
+      const count = wrap ? trailLength : Math.min(trailLength, pointsFromStart);
+      for (let i = count - 1; i >= 0; i--) {
+        const samplePhase = target - i * advance;
+        const wrappedPhase = ((samplePhase % curve.period) + curve.period) % curve.period;
+        const elapsed = targetTime - i * step;
+        const point = curve.fn(wrappedPhase, elapsed, EMPTY_PARAMS);
+        trail.push(point.x, point.y);
+      }
+    },
+    startMorph(target, strategy = "normalized") {
+      const resolvedTarget = resolveCurve(target);
+      if (morphCurveB !== null && _morphAlpha !== null) {
+        const frozenAlpha = _morphAlpha;
+        const frozenA = curve;
+        const frozenB = morphCurveB;
+        const frozenStrategy = _morphStrategy;
+        curve = {
+          ...frozenB,
+          fn: (samplePhase, elapsed, params) => {
+            const a = frozenA.fn(samplePhase, elapsed, params);
+            const phaseB =
+              frozenStrategy === "normalized"
+                ? (samplePhase / frozenA.period) * frozenB.period
+                : samplePhase;
+            const b = frozenB.fn(phaseB, elapsed, params);
+            return {
+              x: a.x + (b.x - a.x) * frozenAlpha,
+              y: a.y + (b.y - a.y) * frozenAlpha,
+            };
+          },
+        };
+      }
+      _morphStrategy = strategy;
+      morphCurveB = resolvedTarget;
+      _morphAlpha = 0;
+    },
+    setMorphAlpha(alpha) {
+      _morphAlpha = alpha;
+    },
+    completeMorph() {
+      if (morphCurveB !== null) {
+        if (_morphStrategy === "normalized" && curve.period !== morphCurveB.period) {
+          phase = (phase / curve.period) * morphCurveB.period;
+        }
+        curve = morphCurveB;
+      }
+      morphCurveB = null;
+      _morphAlpha = null;
+    },
+    getSarmalSkeleton() {
+      const steps = Math.ceil(curve.period * POINTS_PER_PERIOD_UNIT);
+      const points = new Array(steps);
+      if (morphCurveB !== null && _morphAlpha !== null) {
+        for (let i = 0; i < steps; i++) {
+          const samplePhase = (i / (steps - 1)) * curve.period;
+          const a = sampleSkeleton(curve, samplePhase);
+          const phaseB =
+            _morphStrategy === "normalized"
+              ? (samplePhase / curve.period) * morphCurveB.period
+              : samplePhase;
+          const b = sampleSkeleton(morphCurveB, phaseB);
+          points[i] = {
+            x: a.x + (b.x - a.x) * _morphAlpha,
+            y: a.y + (b.y - a.y) * _morphAlpha,
+          };
+        }
+        return points;
+      }
+      for (let i = 0; i < steps; i++) {
+        const samplePhase = (i / (steps - 1)) * curve.period;
+        points[i] = sampleSkeleton(curve, samplePhase);
+      }
+      return points;
+    },
+    setSpeed(speed) {
+      if (!Number.isFinite(speed)) {
+        throw new Error("speed must be a finite number");
+      }
+      if (_speedTransition !== null) {
+        _speedTransition.reject(new Error("Speed transition cancelled"));
+        _speedTransition = null;
+      }
+      userSpeedOverride = speed;
+    },
+    getSpeed() {
+      return userSpeedOverride ?? curve.speed;
+    },
+    resetSpeed() {
+      userSpeedOverride = null;
+    },
+    setSpeedOver(speed, duration) {
+      if (!Number.isFinite(speed)) {
+        throw new Error("speed must be a finite number");
+      }
+      if (!Number.isFinite(duration) || duration <= 0) {
+        throw new Error("duration must be a finite number greater than 0");
+      }
+      if (_speedTransition !== null) {
+        _speedTransition.reject(new Error("Speed transition cancelled"));
+        _speedTransition = null;
+      }
+      const from = userSpeedOverride ?? curve.speed;
+      return new Promise((resolve, reject) => {
+        _speedTransition = { from, to: speed, elapsed: 0, duration, resolve, reject };
+      });
+    },
+    cancelSpeedTransition() {
+      if (_speedTransition !== null) {
+        _speedTransition.reject(new Error("Speed transition cancelled"));
+        _speedTransition = null;
+      }
+    },
+  };
+}
+
+// src/renderer-shared.ts
+var FIT_PADDING = 0.1;
+var FIT_PADDING_MIN = 4;
+function computeBoundaries(pts, logicalWidth, logicalHeight, minPaddingPx = FIT_PADDING_MIN) {
+  if (pts.length === 0) return null;
+  const first = pts[0];
+  let minX = first.x,
+    maxX = first.x,
+    minY = first.y,
+    maxY = first.y;
+  for (const p of pts) {
+    if (p.x < minX) {
+      minX = p.x;
+    }
+    if (p.x > maxX) {
+      maxX = p.x;
+    }
+    if (p.y < minY) {
+      minY = p.y;
+    }
+    if (p.y > maxY) {
+      maxY = p.y;
+    }
+  }
+  const w = maxX - minX;
+  const h = maxY - minY;
+  if (w === 0 && h === 0) {
+    throw new Error(
+      "[sarmal] Degenerate curve: all skeleton points are identical. Check that your curve fn returns distinct points for different values of t.",
+    );
+  }
+  const scaleXProportional = logicalWidth / (w * (1 + FIT_PADDING * 2));
+  const scaleYProportional = logicalHeight / (h * (1 + FIT_PADDING * 2));
+  const scaleXMinPadding = (logicalWidth - minPaddingPx * 2) / w;
+  const scaleYMinPadding = (logicalHeight - minPaddingPx * 2) / h;
+  const scale = Math.min(
+    scaleXProportional,
+    scaleYProportional,
+    scaleXMinPadding,
+    scaleYMinPadding,
+  );
+  return {
+    scale,
+    offsetX: (logicalWidth - w * scale) / 2 - minX * scale,
+    offsetY: (logicalHeight - h * scale) / 2 - minY * scale,
+  };
+}
+function hexToRgb(hex) {
+  const n = parseInt(hex.slice(1), 16);
+  return { r: n >> 16, g: (n >> 8) & 255, b: n & 255 };
+}
+
+// src/terminal.ts
+var DEFAULT_TRAIL_HEX = "#ec5571";
+var DEFAULT_FPS = 30;
+var DEFAULT_SIZE = 16;
+var BRIGHTNESS_HEAD = 1;
+var BRIGHTNESS_TAIL = 0.15;
+var BRAILLE_BASE = 10240;
+var BRAILLE_BIT = [
+  [1, 8],
+  [2, 16],
+  [4, 32],
+  [64, 128],
+];
+function brailleChar(bits) {
+  return String.fromCodePoint(BRAILLE_BASE + (bits & 255));
+}
+function brailleBit(row, col) {
+  return BRAILLE_BIT[row][col];
+}
+function dotToCell(dotCol, dotRow) {
+  return {
+    charCol: Math.floor(dotCol / 2),
+    charRow: Math.floor(dotRow / 4),
+    dotColInCell: dotCol % 2,
+    dotRowInCell: dotRow % 4,
+  };
+}
+function detectColor() {
+  const colorterm = (process.env.COLORTERM ?? "").toLowerCase();
+  if (colorterm === "truecolor" || colorterm === "24bit") {
+    return "truecolor";
+  }
+  const term = (process.env.TERM ?? "").toLowerCase();
+  if (term.includes("256color")) {
+    return "256-color";
+  }
+  if (term.includes("truecolor") || term.includes("24bit")) {
+    return "truecolor";
+  }
+  if (colorterm !== "") {
+    return "256-color";
+  }
+  if (term !== "" && term !== "linux" && term !== "dumb") {
+    return "256-color";
+  }
+  return "monochrome";
+}
+function rgbTo256(r, g, b) {
+  const avg = Math.round((r + g + b) / 3);
+  if (Math.abs(r - avg) <= 4 && Math.abs(g - avg) <= 4 && Math.abs(b - avg) <= 4) {
+    if (avg <= 8) {
+      return 16;
+    }
+    return 232 + Math.min(23, Math.round((avg - 8) / 10));
+  }
+  const ri = Math.round((r / 255) * 5);
+  const gi = Math.round((g / 255) * 5);
+  const bi = Math.round((b / 255) * 5);
+  return 16 + 36 * ri + 6 * gi + bi;
+}
+function dimColor(hex, brightness) {
+  const c = hexToRgb(hex);
+  return {
+    r: Math.round(c.r * brightness),
+    g: Math.round(c.g * brightness),
+    b: Math.round(c.b * brightness),
+  };
+}
+var AR = "\x1B[0m";
+function ansiTruecolorFg(r, g, b) {
+  return `\x1B[38;2;${r};${g};${b}m`;
+}
+function ansi256Fg(code) {
+  return `\x1B[38;5;${code}m`;
+}
+function ansiColor(r, g, b, colorCap) {
+  if (colorCap === "truecolor") {
+    return ansiTruecolorFg(r, g, b);
+  }
+  if (colorCap === "256-color") {
+    return ansi256Fg(rgbTo256(r, g, b));
+  }
+  return "";
+}
+function snapCol(col, max) {
+  return Math.max(0, Math.min(max - 1, Math.round(col)));
+}
+function applyBoundary(x, y, scale, offsetX, offsetY) {
+  return {
+    screenX: x * scale + offsetX,
+    screenY: y * scale + offsetY,
+  };
+}
+function renderFrame(
+  trail,
+  trailCount,
+  charWidth,
+  charHeight,
+  scale,
+  offsetX,
+  offsetY,
+  trailRgb,
+  headRgb,
+  colorCap,
+) {
+  const dotWidth = charWidth * 2;
+  const dotHeight = charHeight * 4;
+  const grid = Array.from({ length: charHeight }, () =>
+    Array.from({ length: charWidth }, () => ({ bits: 0, brightness: 0, isHead: false })),
+  );
+  for (let i = 0; i < trailCount; i++) {
+    const pt = trail[i];
+    const t = trailCount > 1 ? i / (trailCount - 1) : 1;
+    const brightness = BRIGHTNESS_TAIL + (BRIGHTNESS_HEAD - BRIGHTNESS_TAIL) * t;
+    const { screenX, screenY } = applyBoundary(pt.x, pt.y, scale, offsetX, offsetY);
+    const dotCol = snapCol(screenX, dotWidth);
+    const dotRow = snapCol(screenY, dotHeight);
+    const cell = dotToCell(dotCol, dotRow);
+    if (
+      cell.charRow < 0 ||
+      cell.charRow >= charHeight ||
+      cell.charCol < 0 ||
+      cell.charCol >= charWidth
+    ) {
+      continue;
+    }
+    const c = grid[cell.charRow][cell.charCol];
+    c.bits |= BRAILLE_BIT[cell.dotRowInCell][cell.dotColInCell];
+    if (brightness > c.brightness) {
+      c.brightness = brightness;
+    }
+    if (i === trailCount - 1) {
+      c.isHead = true;
+    }
+  }
+  if (colorCap !== "monochrome") {
+    return renderColorFrame(grid, charWidth, charHeight, trailRgb, headRgb, colorCap);
+  }
+  return renderMonochromeFrame(grid, charWidth, charHeight);
+}
+function renderColorFrame(grid, charWidth, charHeight, trailRgb, headRgb, colorCap) {
+  const lines = [];
+  for (let row = 0; row < charHeight; row++) {
+    let line = "";
+    for (let col = 0; col < charWidth; col++) {
+      const cell = grid[row][col];
+      if (cell.bits === 0) {
+        line += " ";
+        continue;
+      }
+      const ch = brailleChar(cell.bits);
+      if (cell.isHead) {
+        line += ansiColor(headRgb.r, headRgb.g, headRgb.b, colorCap) + ch + AR;
+      } else {
+        const r = Math.round(trailRgb.r * cell.brightness);
+        const g = Math.round(trailRgb.g * cell.brightness);
+        const b = Math.round(trailRgb.b * cell.brightness);
+        line += ansiColor(r, g, b, colorCap) + ch + AR;
+      }
+    }
+    lines.push(line);
+  }
+  return lines.join("\n");
+}
+function renderMonochromeFrame(grid, charWidth, charHeight) {
+  const lines = [];
+  for (let row = 0; row < charHeight; row++) {
+    let line = "";
+    for (let col = 0; col < charWidth; col++) {
+      const cell = grid[row][col];
+      if (cell.bits === 0) {
+        line += " ";
+        continue;
+      }
+      if (cell.isHead) {
+        line += "\u28FF";
+      } else {
+        line += brailleChar(cell.bits);
+      }
+    }
+    lines.push(line);
+  }
+  return lines.join("\n");
+}
+function terminalSarmal(stream, curveDef, options) {
+  if (!stream.isTTY) {
+    return () => {};
+  }
+  const size = options?.size ?? DEFAULT_SIZE;
+  const fps = options?.fps ?? DEFAULT_FPS;
+  const trailHex = options?.trailColor ?? DEFAULT_TRAIL_HEX;
+  const headHex = options?.headColor ?? trailHex;
+  const userSpeed = options?.speed;
+  const colorCap = detectColor();
+  const trailRgb = hexToRgb(trailHex);
+  const headRgb = hexToRgb(headHex);
+  const engine = createEngine(curveDef);
+  if (userSpeed !== void 0) {
+    engine.setSpeed(userSpeed);
+  }
+  const charWidth = size;
+  const charHeight = Math.ceil(size / 2);
+  const skeleton = engine.getSarmalSkeleton();
+  const b = computeBoundaries(skeleton, charWidth * 2, charHeight * 4, 1);
+  if (!b) {
+    return () => {};
+  }
+  const { scale, offsetX, offsetY } = b;
+  let running = true;
+  let firstFrame = true;
+  stream.write("\x1B[?25l");
+  function cleanup() {
+    running = false;
+    stream.write("\x1B[?25h");
+    stream.write("\n");
+  }
+  const onSigint = () => {
+    cleanup();
+    process.exit(0);
+  };
+  process.on("SIGINT", onSigint);
+  function render() {
+    const delta = 1 / fps;
+    const trail = engine.tick(delta);
+    const trailCount = engine.trailCount;
+    const frame = renderFrame(
+      trail,
+      trailCount,
+      charWidth,
+      charHeight,
+      scale,
+      offsetX,
+      offsetY,
+      trailRgb,
+      headRgb,
+      colorCap,
+    );
+    if (firstFrame) {
+      firstFrame = false;
+      stream.write(frame + "\n");
+      return;
+    }
+    const rows = charHeight;
+    stream.write(`\x1B[${rows}A`);
+    const lines = frame.split("\n");
+    for (const line of lines) {
+      stream.write(line + "\n");
+    }
+  }
+  render();
+  const interval = setInterval(() => {
+    if (!running) {
+      return;
+    }
+    render();
+  }, 1e3 / fps);
+  function stop() {
+    clearInterval(interval);
+    process.off("SIGINT", onSigint);
+    cleanup();
+  }
+  return stop;
+}
+
+export { brailleBit, brailleChar, detectColor, dimColor, dotToCell, rgbTo256, terminalSarmal };
+//# sourceMappingURL=terminal.js.map
+//# sourceMappingURL=terminal.js.map