ripple-text 0.1.0

package/README.md

@@ -0,0 +1,120 @@
+# ripple-text
+
+Physics-driven text animation engine. Characters react to mouse and touch
+interactions through expanding ripple waves and continuous field effects like
+water caustics.
+
+[Demo & homepage](https://ilia.to)
+
+## Install
+
+```bash
+npm install ripple-text
+```
+
+## Usage
+
+```typescript
+import {
+  RippleTextEngine,
+  WaterField,
+  WaveRipple,
+  layoutText,
+} from "ripple-text";
+
+const canvas = document.getElementById("canvas") as HTMLCanvasElement;
+const ctx = canvas.getContext("2d")!;
+
+const field = new WaterField();
+const ripple = new WaveRipple();
+
+const engine = new RippleTextEngine(canvas, field, ripple, {
+  bgColor: "#020814",
+});
+
+const letters = layoutText(ctx, "Hello world", { fontSize: 24, margin: 40 });
+engine.setLetters(letters);
+engine.start();
+```
+
+### Tuning settings at runtime
+
+```typescript
+engine.updateSettings({
+  gradientForce: 25000,
+  springForce: 5,
+  damping: 0.92,
+  maxDisplacement: 150,
+});
+```
+
+### Custom colors
+
+```typescript
+const engine = new RippleTextEngine(canvas, field, ripple, {
+  colorBuckets: 10,
+  buildColors(n) {
+    return Array.from({ length: n }, (_, i) => {
+      const t = i / (n - 1);
+      return `rgba(${100 + t * 155}, ${180 + t * 75}, 255, ${0.8 + t * 0.2})`;
+    });
+  },
+});
+```
+
+### Extracting text from the DOM
+
+```typescript
+import { extractTextFromDOM } from "ripple-text";
+
+const letters = extractTextFromDOM(document.body, 5000);
+engine.setLetters(letters);
+```
+
+## API
+
+### `RippleTextEngine(canvas, field, ripple, settings?)`
+
+Main class. Handles physics simulation, rendering, and pointer interaction.
+
+- **`setLetters(letters)`** — set the characters to animate
+- **`updateSettings(patch)`** — update physics/rendering settings live
+- **`resize(w, h)`** — call on window resize
+- **`start()`** — begin the animation loop and attach event listeners
+- **`stop()`** — stop the loop and remove listeners
+
+### `layoutText(ctx, text, options)`
+
+Lays out plain text on a canvas with word wrapping. Returns an array of letter
+positions.
+
+Options: `fontSize`, `margin`, `lineHeight`, `font`.
+
+### `extractTextFromDOM(root, maxChars?)`
+
+Walks the DOM tree and extracts visible characters with their screen positions
+and computed fonts.
+
+### `WaterField` / `WaveRipple`
+
+Built-in implementations of the `FieldEffect` and `RippleSource` interfaces.
+Provide your own to create custom effects.
+
+## Settings
+
+| Setting           | Default     | Description                                     |
+| ----------------- | ----------- | ----------------------------------------------- |
+| `gradientForce`   | `18000`     | How strongly field gradients push letters       |
+| `springForce`     | `3.0`       | Restoration force toward original position      |
+| `darkSpringBoost` | `8.0`       | Extra spring force in dark field regions        |
+| `damping`         | `0.88`      | Velocity damping per frame                      |
+| `maxDisplacement` | `120`       | Max pixel distance from origin                  |
+| `fieldScale`      | `3`         | Field simulation downscale factor               |
+| `rippleInterval`  | `90`        | Milliseconds between ripples while pointer held |
+| `colorBuckets`    | `10`        | Number of displacement-based color steps        |
+| `bgColor`         | `"#020814"` | Canvas background color                         |
+| `showFps`         | `false`     | Show FPS counter                                |
+
+## License
+
+MIT

package/dist/index.js

@@ -0,0 +1,320 @@
+const M = 0.016666666666666666, P = {
+  gradientForce: 18e3,
+  springForce: 3,
+  darkSpringBoost: 8,
+  damping: 0.88,
+  maxDisplacement: 120,
+  fieldScale: 3,
+  rippleInterval: 90,
+  colorBuckets: 10,
+  bgColor: "rgb(255,254,250)",
+  showFps: !1,
+  buildColors(p) {
+    const e = [];
+    for (let t = 0; t < p; t++) {
+      const i = t / (p - 1), s = Math.round(50 - i * 40);
+      e.push(`rgba(${s},${s},${s},${(0.75 + i * 0.25).toFixed(2)})`);
+    }
+    return e;
+  }
+};
+class R {
+  constructor(e, t, i, s) {
+    this.letters = [], this.colors = [], this.rafId = 0, this.lastFrameTime = 0, this.running = !1, this.fpsFrames = 0, this.fpsLastTime = 0, this.fpsDisplay = 0, this.pointerDown = !1, this.pointerX = 0, this.pointerY = 0, this.prevPointerX = 0, this.prevPointerY = 0, this.pointerSpeed = 0, this.lastRippleTime = 0, this.canvas = e, this.ctx = e.getContext("2d"), this.field = t, this.ripple = i, this.settings = { ...P, ...s }, this.colors = this.settings.buildColors(this.settings.colorBuckets);
+    const r = Math.ceil(e.width / this.settings.fieldScale), a = Math.ceil(e.height / this.settings.fieldScale);
+    this.field.resize(r, a), this.ripple.resize(e.width, e.height), this._onDown = (h) => {
+      this.pointerDown = !0, this.pointerX = h.clientX, this.pointerY = h.clientY, this.prevPointerX = this.pointerX, this.prevPointerY = this.pointerY, this.pointerSpeed = 0, this.ripple.addRipple(this.pointerX, this.pointerY, this.lastFrameTime), this.lastRippleTime = this.lastFrameTime;
+    }, this._onMove = (h) => {
+      if (!this.pointerDown) return;
+      this.prevPointerX = this.pointerX, this.prevPointerY = this.pointerY, this.pointerX = h.clientX, this.pointerY = h.clientY;
+      const o = this.pointerX - this.prevPointerX, c = this.pointerY - this.prevPointerY;
+      this.pointerSpeed = Math.sqrt(o * o + c * c);
+    }, this._onUp = () => {
+      this.pointerDown = !1, this.pointerSpeed = 0;
+    }, this._onTouchStart = (h) => {
+      const o = h.touches[0];
+      o && (this.pointerDown = !0, this.pointerX = o.clientX, this.pointerY = o.clientY, this.prevPointerX = this.pointerX, this.prevPointerY = this.pointerY, this.pointerSpeed = 0, this.ripple.addRipple(this.pointerX, this.pointerY, this.lastFrameTime), this.lastRippleTime = this.lastFrameTime);
+    }, this._onTouchMove = (h) => {
+      const o = h.touches[0];
+      if (!o || !this.pointerDown) return;
+      this.prevPointerX = this.pointerX, this.prevPointerY = this.pointerY, this.pointerX = o.clientX, this.pointerY = o.clientY;
+      const c = this.pointerX - this.prevPointerX, n = this.pointerY - this.prevPointerY;
+      this.pointerSpeed = Math.sqrt(c * c + n * n);
+    }, this._onTouchEnd = () => {
+      this.pointerDown = !1, this.pointerSpeed = 0;
+    };
+  }
+  // ——— Public API ———
+  setLetters(e) {
+    this.letters = e.map((t) => ({
+      char: t.char,
+      ox: t.x,
+      oy: t.y,
+      x: t.x,
+      y: t.y,
+      vx: 0,
+      vy: 0,
+      font: t.font
+    }));
+  }
+  updateSettings(e) {
+    Object.assign(this.settings, e), (e.buildColors || e.colorBuckets) && (this.colors = this.settings.buildColors(this.settings.colorBuckets));
+  }
+  resize(e, t) {
+    this.canvas.width = e, this.canvas.height = t;
+    const i = Math.ceil(e / this.settings.fieldScale), s = Math.ceil(t / this.settings.fieldScale);
+    this.field.resize(i, s), this.ripple.resize(e, t);
+  }
+  start() {
+    this.running && this.stop(), this.running = !0, this.canvas.addEventListener("mousedown", this._onDown), this.canvas.addEventListener("mousemove", this._onMove), window.addEventListener("mouseup", this._onUp), this.canvas.addEventListener("touchstart", this._onTouchStart, {
+      passive: !0
+    }), this.canvas.addEventListener("touchmove", this._onTouchMove, {
+      passive: !0
+    }), window.addEventListener("touchend", this._onTouchEnd);
+    const e = (t) => {
+      this.running && (this.lastFrameTime = t, this.fpsFrames++, t - this.fpsLastTime >= 1e3 && (this.fpsDisplay = this.fpsFrames, this.fpsFrames = 0, this.fpsLastTime = t), this.emitRipples(t), this.updatePhysics(t), this.render(), this.rafId = requestAnimationFrame(e));
+    };
+    this.rafId = requestAnimationFrame(e);
+  }
+  stop() {
+    this.running = !1, cancelAnimationFrame(this.rafId), this.rafId = 0, this.pointerDown = !1, this.pointerSpeed = 0, this.canvas.removeEventListener("mousedown", this._onDown), this.canvas.removeEventListener("mousemove", this._onMove), window.removeEventListener("mouseup", this._onUp), this.canvas.removeEventListener("touchstart", this._onTouchStart), this.canvas.removeEventListener("touchmove", this._onTouchMove), window.removeEventListener("touchend", this._onTouchEnd);
+  }
+  // ——— Private ———
+  emitRipples(e) {
+    if (!this.pointerDown) return;
+    const t = Math.min(this.pointerSpeed * 0.1, 1), i = 800 * (1 - t) + this.settings.rippleInterval * t;
+    e - this.lastRippleTime >= i && (this.lastRippleTime = e, this.ripple.addRipple(this.pointerX, this.pointerY, e)), this.pointerSpeed *= 0.85;
+  }
+  updatePhysics(e) {
+    const t = this.settings, i = t.fieldScale;
+    this.field.update(e), this.ripple.update(e), this.ripple.prune(e);
+    for (const s of this.letters) {
+      const r = s.x / i, a = s.y / i, { brightness: h, gradX: o, gradY: c } = this.field.sample(r, a), n = h * h;
+      s.vx -= o * t.gradientForce * n * M, s.vy -= c * t.gradientForce * n * M;
+      const [l, d, f] = this.ripple.computeForce(
+        s.x,
+        s.y,
+        e
+      );
+      s.vx += l * M, s.vy += d * M;
+      const m = s.ox - s.x, g = s.oy - s.y, v = 1 - h, F = 1 - f * 0.85, S = (t.springForce + v * t.darkSpringBoost) * F;
+      s.vx += m * S * M, s.vy += g * S * M, s.vx *= t.damping, s.vy *= t.damping, s.x += s.vx * M, s.y += s.vy * M;
+      const x = s.x - s.ox, w = s.y - s.oy, u = Math.sqrt(x * x + w * w);
+      if (u > t.maxDisplacement) {
+        const y = t.maxDisplacement / u;
+        s.x = s.ox + x * y, s.y = s.oy + w * y, s.vx *= 0.5, s.vy *= 0.5;
+      }
+    }
+  }
+  render() {
+    const { ctx: e, canvas: t, settings: i } = this, s = t.width, r = t.height;
+    e.fillStyle = i.bgColor, e.fillRect(0, 0, s, r);
+    const a = 1 / i.maxDisplacement, h = i.colorBuckets - 1;
+    e.textBaseline = "alphabetic";
+    let o = "";
+    for (const c of this.letters) {
+      const n = c.x - c.ox, l = c.y - c.oy, f = Math.min(Math.sqrt(n * n + l * l) * a, 1) * h + 0.5 | 0;
+      c.font !== o && (e.font = c.font, o = c.font), e.fillStyle = this.colors[f], e.fillText(c.char, c.x, c.y);
+    }
+    if (i.showFps) {
+      e.font = "11px monospace", e.textBaseline = "bottom", e.fillStyle = "rgba(100,180,255,0.4)";
+      const c = `${this.fpsDisplay} fps | ${this.letters.length} chars | ${this.ripple.activeCount()} ripples`, n = e.measureText(c).width;
+      e.fillText(c, s - n - 10, r - 10);
+    }
+  }
+}
+const B = 0.5 * (Math.sqrt(3) - 1), _ = (3 - Math.sqrt(3)) / 6, X = [1, -1, 1, -1, 1, -1, 0, 0], D = [1, 1, -1, -1, 0, 0, 1, -1], b = new Uint8Array(512), Y = new Uint8Array(512), T = new Uint8Array(256);
+for (let p = 0; p < 256; p++) T[p] = p;
+for (let p = 255; p > 0; p--) {
+  const e = Math.floor(Math.random() * (p + 1));
+  [T[p], T[e]] = [T[e], T[p]];
+}
+for (let p = 0; p < 512; p++)
+  b[p] = T[p & 255], Y[p] = b[p] & 7;
+function E(p, e) {
+  const t = (p + e) * B, i = Math.floor(p + t), s = Math.floor(e + t), r = (i + s) * _, a = p - (i - r), h = e - (s - r), o = a > h ? 1 : 0, c = 1 - o, n = a - o + _, l = h - c + _, d = a - 1 + 2 * _, f = h - 1 + 2 * _, m = i & 255, g = s & 255;
+  let v = 0, F = 0, S = 0, x = 0.5 - a * a - h * h;
+  if (x >= 0) {
+    x *= x;
+    const y = Y[m + b[g]];
+    v = x * x * (X[y] * a + D[y] * h);
+  }
+  let w = 0.5 - n * n - l * l;
+  if (w >= 0) {
+    w *= w;
+    const y = Y[m + o + b[g + c]];
+    F = w * w * (X[y] * n + D[y] * l);
+  }
+  let u = 0.5 - d * d - f * f;
+  if (u >= 0) {
+    u *= u;
+    const y = Y[m + 1 + b[g + 1]];
+    S = u * u * (X[y] * d + D[y] * f);
+  }
+  return 70 * (v + F + S);
+}
+const A = {
+  noiseScale: 4e-3,
+  timeSpeed: 3e-4,
+  sharpness: 0.6
+};
+class $ {
+  constructor(e) {
+    this.w = 0, this.h = 0, this.brightness = new Float32Array(0), this.gradXBuf = new Float32Array(0), this.gradYBuf = new Float32Array(0), this.frameCount = 0, this.settings = { ...A, ...e };
+  }
+  resize(e, t) {
+    this.w = e, this.h = t;
+    const i = e * t;
+    this.brightness = new Float32Array(i), this.gradXBuf = new Float32Array(i), this.gradYBuf = new Float32Array(i);
+  }
+  update(e) {
+    this.frameCount++;
+    const { w: t, h: i, brightness: s } = this;
+    if ((this.frameCount & 1) === 0) {
+      const r = this.settings.noiseScale, a = e * this.settings.timeSpeed, h = this.settings.sharpness, o = Math.abs(h - 1) > 0.01 && Math.abs(h - 0.5) > 0.01, c = Math.abs(h - 0.5) < 0.01, n = a * 0.7, l = a * 0.5, d = a * 0.4, f = a * 0.3, m = a * 0.2, g = a * 0.6;
+      for (let v = 0; v < i; v++) {
+        const F = v * r, S = v * t;
+        for (let x = 0; x < t; x++) {
+          const w = x * r;
+          let u = 0;
+          u += E(w + n, F + l) * 0.5, u += E(w * 2 - d, F * 2 + f) * 0.25, u += E(w * 4 + m, F * 4 - g) * 0.125, u = u < 0 ? -u : u, c ? u = Math.sqrt(u) : o && (u = Math.pow(u, h)), s[S + x] = 1 - u;
+        }
+      }
+    }
+    this.computeGradients();
+  }
+  sample(e, t) {
+    const { w: i, h: s, brightness: r, gradXBuf: a, gradYBuf: h } = this, o = i - 1.001, c = s - 1.001;
+    e < 0 ? e = 0 : e > o && (e = o), t < 0 ? t = 0 : t > c && (t = c);
+    const n = e | 0, l = t | 0, d = e - n, f = t - l, m = l * i + n, g = 1 - d, v = 1 - f, F = r[m] * g * v + r[m + 1] * d * v + r[m + i] * g * f + r[m + i + 1] * d * f, S = (t | 0) * i + (e | 0);
+    return { brightness: F, gradX: a[S], gradY: h[S] };
+  }
+  computeGradients() {
+    const { w: e, h: t, brightness: i, gradXBuf: s, gradYBuf: r } = this;
+    for (let a = 0; a < t; a++) {
+      const h = a * e, o = a > 1 ? (a - 2) * e : 0, c = a < t - 2 ? (a + 2) * e : (t - 1) * e;
+      for (let n = 0; n < e; n++) {
+        const l = n > 1 ? n - 2 : 0, d = n < e - 2 ? n + 2 : e - 1;
+        s[h + n] = (i[h + d] - i[h + l]) * 0.25, r[h + n] = (i[c + n] - i[o + n]) * 0.25;
+      }
+    }
+  }
+}
+const C = {
+  amplitude: 1.25,
+  wavelength: 800,
+  decay: 48e-4,
+  force: 2350,
+  waveCenterY: -0.05,
+  waveAmpMul: 1.4
+};
+class k {
+  constructor(e) {
+    this.ripples = [], this.settings = { ...C, ...e };
+  }
+  resize(e, t) {
+  }
+  addRipple(e, t, i) {
+    const s = this.settings;
+    this.ripples.push({
+      cx: e,
+      cy: t,
+      startTime: i,
+      wavelength: s.wavelength,
+      amplitude: s.amplitude,
+      decay: s.decay,
+      _radius: 0,
+      _timeFade: 1,
+      _ringWidth: s.wavelength * 0.15,
+      _baseSpeed: s.wavelength * 2e-3
+    });
+  }
+  update(e) {
+    for (const t of this.ripples) {
+      const i = e - t.startTime;
+      t._timeFade = Math.exp(-i * t.decay), t._ringWidth = t.wavelength * 0.15, t._baseSpeed = t.wavelength * 2e-3;
+      const s = 2 * Math.PI * i / t.wavelength, r = (1 - Math.cos(s + this.settings.waveCenterY * Math.PI)) * this.settings.waveAmpMul, a = t._baseSpeed * i * 0.5 * r;
+      t._radius = t._baseSpeed * i * 0.3 + a * 0.7;
+    }
+  }
+  prune(e) {
+    for (let t = this.ripples.length - 1; t >= 0; t--)
+      this.ripples[t]._timeFade < 0.01 && this.ripples.splice(t, 1);
+  }
+  computeForce(e, t, i) {
+    let s = 0, r = 0, a = 0;
+    const h = this.settings.force;
+    for (const o of this.ripples) {
+      const c = e - o.cx, n = t - o.cy, l = c * c + n * n;
+      if (l < 1) continue;
+      const d = Math.sqrt(l), f = d - o._radius, m = o._ringWidth, g = m * 3;
+      if (f > g || f < -g) continue;
+      const v = -f / m, F = f / m, S = Math.exp(-F * F), x = f < 0 ? Math.exp(f / m) : Math.exp(-f * 2 / m), w = v * S * h * 1.5, u = x * h * o._baseSpeed * 0.8, y = (w + u) * o._timeFade * o.amplitude, L = 1 / d;
+      s += c * L * y, r += n * L * y, a = Math.max(a, S * o._timeFade);
+    }
+    return [s, r, a];
+  }
+  activeCount() {
+    return this.ripples.length;
+  }
+}
+function W(p, e = 4e3) {
+  const t = [], i = document.createTreeWalker(p, NodeFilter.SHOW_TEXT), s = document.createRange();
+  let r = i.nextNode();
+  for (; r && t.length < e; ) {
+    const a = r.textContent ?? "";
+    if (!a.trim()) {
+      r = i.nextNode();
+      continue;
+    }
+    const h = r.parentElement;
+    if (!h) {
+      r = i.nextNode();
+      continue;
+    }
+    const o = getComputedStyle(h);
+    if (o.display === "none" || o.visibility === "hidden" || o.opacity === "0") {
+      r = i.nextNode();
+      continue;
+    }
+    const c = `${o.fontStyle} ${o.fontWeight} ${o.fontSize} ${o.fontFamily}`;
+    for (let n = 0; n < a.length && t.length < e; n++) {
+      const l = a[n];
+      if (/\s/.test(l)) continue;
+      s.setStart(r, n), s.setEnd(r, n + 1);
+      const d = s.getBoundingClientRect();
+      d.width === 0 || d.height === 0 || t.push({
+        char: l,
+        x: d.left,
+        y: d.top + d.height * 0.75,
+        font: c
+      });
+    }
+    r = i.nextNode();
+  }
+  return s.detach(), t;
+}
+function q(p, e, t = {}) {
+  const i = t.fontSize ?? 16, s = t.font ?? `${i}px "Courier New", monospace`, r = t.margin ?? 40, a = (t.maxWidth ?? p.canvas.width) - r * 2, h = t.maxHeight ?? p.canvas.height, o = t.lineHeight ?? i * 1.6;
+  p.font = s;
+  const c = [];
+  let n = r, l = r + i;
+  const d = e.split(" ");
+  for (const f of d) {
+    const m = p.measureText(f + " ").width;
+    if (n + m > r + a && n > r && (n = r, l += o), l > h - r) break;
+    for (const g of f) {
+      const v = p.measureText(g).width;
+      c.push({ char: g, x: n, y: l, font: s }), n += v;
+    }
+    n += p.measureText(" ").width;
+  }
+  return c;
+}
+export {
+  R as RippleTextEngine,
+  $ as WaterField,
+  k as WaveRipple,
+  W as extractTextFromDOM,
+  q as layoutText
+};

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "ripple-text",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Physics-driven text effect with pluggable field and ripple algorithms",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "dev": "vite demo",
+    "build": "tsc && vite build",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "prepare": "husky"
+  },
+  "lint-staged": {
+    "*.{ts,js}": [
+      "eslint --fix",
+      "prettier --write"
+    ],
+    "*.{json,md,yml,yaml}": [
+      "prettier --write"
+    ]
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "eslint": "^10.1.0",
+    "eslint-config-prettier": "^10.1.8",
+    "husky": "^9.1.7",
+    "lint-staged": "^16.4.0",
+    "prettier": "^3.8.1",
+    "typescript": "^5.7.0",
+    "typescript-eslint": "^8.58.0",
+    "vite": "^6.3.0"
+  }
+}