unicode-animations 0.2.1 → 1.0.0

package/README.md

@@ -4,7 +4,7 @@ Unicode spinner animations as raw frame data — no dependencies, works everywhe
 
 ## Demo
 
-See all 22 spinners animating live:
+See all 18 spinners animating live:
 
 ```bash
 npx unicode-animations --web     # open browser demo
@@ -171,15 +171,6 @@ el.textContent = '✔ Synced';
 | `fillsweep` | 11 | 100ms |
 | `diagswipe` | 16 | 60ms |
 
-### Non-braille classics
-
-| Name | Preview | Interval |
-|------|---------|----------|
-| `arc` | `◜ ◠ ◝ ◞ ◡ ◟` | 100ms |
-| `halfmoon` | `◐ ◓ ◑ ◒` | 180ms |
-| `line` | `\| / — \` | 100ms |
-| `blocks` | `▁ ▂ ▃ ▄ ▅ ▆ ▇ █ ▇ ▆ ▅ ▄ ▃ ▂` | 100ms |
-
 ## Custom spinners
 
 Create your own braille spinners using the grid utilities:
@@ -218,7 +209,7 @@ interface Spinner {
 | `gridToBraille(grid)` | `(boolean[][]) => string` |
 | `makeGrid(rows, cols)` | `(number, number) => boolean[][]` |
 | `Spinner` | TypeScript interface |
-| `BrailleSpinnerName` | Union type of all 22 spinner names |
+| `BrailleSpinnerName` | Union type of all 18 spinner names |
 
 ### Exports from `'unicode-animations/braille'`
 

package/dist/braille.cjs

@@ -56,6 +56,7 @@ function gridToBraille(grid) {
   return result;
 }
 function makeGrid(rows, cols) {
+  if (rows <= 0 || cols <= 0) return [];
   return Array.from({ length: rows }, () => Array(cols).fill(false));
 }
 function genScan() {
@@ -377,24 +378,7 @@ var spinners = {
   checkerboard: { frames: genCheckerboard(), interval: 250 },
   helix: { frames: genHelix(), interval: 80 },
   fillsweep: { frames: genFillSweep(), interval: 100 },
-  diagswipe: { frames: genDiagonalSwipe(), interval: 60 },
-  // === Non-braille classics ===
-  arc: {
-    frames: ["\u25DC", "\u25E0", "\u25DD", "\u25DE", "\u25E1", "\u25DF"],
-    interval: 100
-  },
-  halfmoon: {
-    frames: ["\u25D0", "\u25D3", "\u25D1", "\u25D2"],
-    interval: 180
-  },
-  line: {
-    frames: ["|", "/", "\u2014", "\\"],
-    interval: 100
-  },
-  blocks: {
-    frames: ["\u2581", "\u2582", "\u2583", "\u2584", "\u2585", "\u2586", "\u2587", "\u2588", "\u2587", "\u2586", "\u2585", "\u2584", "\u2583", "\u2582"],
-    interval: 100
-  }
+  diagswipe: { frames: genDiagonalSwipe(), interval: 60 }
 };
 var braille_default = spinners;
 // Annotate the CommonJS export names for ESM import in node:

package/dist/braille.d.cts

@@ -9,7 +9,7 @@ interface Spinner {
     readonly frames: readonly string[];
     readonly interval: number;
 }
-type BrailleSpinnerName = 'braille' | 'braillewave' | 'dna' | 'scan' | 'rain' | 'scanline' | 'pulse' | 'snake' | 'sparkle' | 'cascade' | 'columns' | 'orbit' | 'breathe' | 'waverows' | 'checkerboard' | 'helix' | 'fillsweep' | 'diagswipe' | 'arc' | 'halfmoon' | 'line' | 'blocks';
+type BrailleSpinnerName = 'braille' | 'braillewave' | 'dna' | 'scan' | 'rain' | 'scanline' | 'pulse' | 'snake' | 'sparkle' | 'cascade' | 'columns' | 'orbit' | 'breathe' | 'waverows' | 'checkerboard' | 'helix' | 'fillsweep' | 'diagswipe';
 /**
  * Convert a 2D boolean grid into a braille string.
  * grid[row][col] = true means dot is raised.

package/dist/braille.d.ts

@@ -9,7 +9,7 @@ interface Spinner {
     readonly frames: readonly string[];
     readonly interval: number;
 }
-type BrailleSpinnerName = 'braille' | 'braillewave' | 'dna' | 'scan' | 'rain' | 'scanline' | 'pulse' | 'snake' | 'sparkle' | 'cascade' | 'columns' | 'orbit' | 'breathe' | 'waverows' | 'checkerboard' | 'helix' | 'fillsweep' | 'diagswipe' | 'arc' | 'halfmoon' | 'line' | 'blocks';
+type BrailleSpinnerName = 'braille' | 'braillewave' | 'dna' | 'scan' | 'rain' | 'scanline' | 'pulse' | 'snake' | 'sparkle' | 'cascade' | 'columns' | 'orbit' | 'breathe' | 'waverows' | 'checkerboard' | 'helix' | 'fillsweep' | 'diagswipe';
 /**
  * Convert a 2D boolean grid into a braille string.
  * grid[row][col] = true means dot is raised.

package/dist/braille.global.js

@@ -0,0 +1,385 @@
+"use strict";
+var UnicodeAnimations = (() => {
+  var __defProp = Object.defineProperty;
+  var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+  var __getOwnPropNames = Object.getOwnPropertyNames;
+  var __hasOwnProp = Object.prototype.hasOwnProperty;
+  var __export = (target, all) => {
+    for (var name in all)
+      __defProp(target, name, { get: all[name], enumerable: true });
+  };
+  var __copyProps = (to, from, except, desc) => {
+    if (from && typeof from === "object" || typeof from === "function") {
+      for (let key of __getOwnPropNames(from))
+        if (!__hasOwnProp.call(to, key) && key !== except)
+          __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+    }
+    return to;
+  };
+  var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+  // src/braille.ts
+  var braille_exports = {};
+  __export(braille_exports, {
+    default: () => braille_default,
+    gridToBraille: () => gridToBraille,
+    makeGrid: () => makeGrid,
+    spinners: () => spinners
+  });
+  var BRAILLE_DOT_MAP = [
+    [1, 8],
+    // row 0
+    [2, 16],
+    // row 1
+    [4, 32],
+    // row 2
+    [64, 128]
+    // row 3
+  ];
+  function gridToBraille(grid) {
+    const rows = grid.length;
+    const cols = grid[0] ? grid[0].length : 0;
+    const charCount = Math.ceil(cols / 2);
+    let result = "";
+    for (let c = 0; c < charCount; c++) {
+      let code = 10240;
+      for (let r = 0; r < 4 && r < rows; r++) {
+        for (let d = 0; d < 2; d++) {
+          const col = c * 2 + d;
+          if (col < cols && grid[r] && grid[r][col]) {
+            code |= BRAILLE_DOT_MAP[r][d];
+          }
+        }
+      }
+      result += String.fromCodePoint(code);
+    }
+    return result;
+  }
+  function makeGrid(rows, cols) {
+    if (rows <= 0 || cols <= 0) return [];
+    return Array.from({ length: rows }, () => Array(cols).fill(false));
+  }
+  function genScan() {
+    const W = 8, H = 4, frames = [];
+    for (let pos = -1; pos < W + 1; pos++) {
+      const g = makeGrid(H, W);
+      for (let r = 0; r < H; r++) {
+        for (let c = 0; c < W; c++) {
+          if (c === pos || c === pos - 1) g[r][c] = true;
+        }
+      }
+      frames.push(gridToBraille(g));
+    }
+    return frames;
+  }
+  function genRain() {
+    const W = 8, H = 4, totalFrames = 12, frames = [];
+    const offsets = [0, 3, 1, 5, 2, 7, 4, 6];
+    for (let f = 0; f < totalFrames; f++) {
+      const g = makeGrid(H, W);
+      for (let c = 0; c < W; c++) {
+        const row = (f + offsets[c]) % (H + 2);
+        if (row < H) g[row][c] = true;
+      }
+      frames.push(gridToBraille(g));
+    }
+    return frames;
+  }
+  function genScanLine() {
+    const W = 6, H = 4, frames = [];
+    const positions = [0, 1, 2, 3, 2, 1];
+    for (const row of positions) {
+      const g = makeGrid(H, W);
+      for (let c = 0; c < W; c++) {
+        g[row][c] = true;
+        if (row > 0) g[row - 1][c] = c % 2 === 0;
+      }
+      frames.push(gridToBraille(g));
+    }
+    return frames;
+  }
+  function genPulse() {
+    const W = 6, H = 4, frames = [];
+    const cx = W / 2 - 0.5, cy = H / 2 - 0.5;
+    const radii = [0.5, 1.2, 2, 3, 3.5];
+    for (const r of radii) {
+      const g = makeGrid(H, W);
+      for (let row = 0; row < H; row++) {
+        for (let col = 0; col < W; col++) {
+          const dist = Math.sqrt((col - cx) ** 2 + (row - cy) ** 2);
+          if (Math.abs(dist - r) < 0.9) g[row][col] = true;
+        }
+      }
+      frames.push(gridToBraille(g));
+    }
+    return frames;
+  }
+  function genSnake() {
+    const W = 4, H = 4;
+    const path = [];
+    for (let r = 0; r < H; r++) {
+      if (r % 2 === 0) {
+        for (let c = 0; c < W; c++) path.push([r, c]);
+      } else {
+        for (let c = W - 1; c >= 0; c--) path.push([r, c]);
+      }
+    }
+    const frames = [];
+    for (let i = 0; i < path.length; i++) {
+      const g = makeGrid(H, W);
+      for (let t = 0; t < 4; t++) {
+        const idx = (i - t + path.length) % path.length;
+        g[path[idx][0]][path[idx][1]] = true;
+      }
+      frames.push(gridToBraille(g));
+    }
+    return frames;
+  }
+  function genSparkle() {
+    const patterns = [
+      [1, 0, 0, 1, 0, 0, 1, 0, 0, 0, 1, 0, 0, 1, 0, 0, 0, 1, 0, 0, 1, 0, 0, 1, 1, 0, 0, 0, 0, 1, 0, 0],
+      [0, 1, 0, 0, 1, 0, 0, 1, 1, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 1, 0, 0, 0, 0, 1, 0, 1, 0, 1, 0],
+      [0, 0, 1, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 1, 0, 1, 0, 0, 0, 0, 1, 0, 1, 0, 1, 0, 0, 0, 1],
+      [1, 0, 0, 0, 0, 0, 1, 1, 0, 0, 1, 0, 1, 0, 0, 0, 0, 0, 0, 0, 1, 0, 1, 0, 1, 0, 0, 1, 0, 0, 1, 0],
+      [0, 0, 0, 1, 1, 0, 0, 0, 0, 1, 0, 0, 0, 1, 0, 1, 1, 0, 0, 1, 0, 0, 0, 0, 0, 1, 0, 0, 0, 1, 0, 1],
+      [0, 1, 1, 0, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 1, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 1, 0, 0, 0]
+    ];
+    const W = 8, H = 4, frames = [];
+    for (const pat of patterns) {
+      const g = makeGrid(H, W);
+      for (let r = 0; r < H; r++) {
+        for (let c = 0; c < W; c++) {
+          g[r][c] = !!pat[r * W + c];
+        }
+      }
+      frames.push(gridToBraille(g));
+    }
+    return frames;
+  }
+  function genCascade() {
+    const W = 8, H = 4, frames = [];
+    for (let offset = -2; offset < W + H; offset++) {
+      const g = makeGrid(H, W);
+      for (let r = 0; r < H; r++) {
+        for (let c = 0; c < W; c++) {
+          const diag = c + r;
+          if (diag === offset || diag === offset - 1) g[r][c] = true;
+        }
+      }
+      frames.push(gridToBraille(g));
+    }
+    return frames;
+  }
+  function genColumns() {
+    const W = 6, H = 4, frames = [];
+    for (let col = 0; col < W; col++) {
+      for (let fillTo = H - 1; fillTo >= 0; fillTo--) {
+        const g = makeGrid(H, W);
+        for (let pc = 0; pc < col; pc++) {
+          for (let r = 0; r < H; r++) g[r][pc] = true;
+        }
+        for (let r = fillTo; r < H; r++) g[r][col] = true;
+        frames.push(gridToBraille(g));
+      }
+    }
+    const full = makeGrid(H, W);
+    for (let r = 0; r < H; r++) for (let c = 0; c < W; c++) full[r][c] = true;
+    frames.push(gridToBraille(full));
+    frames.push(gridToBraille(makeGrid(H, W)));
+    return frames;
+  }
+  function genOrbit() {
+    const W = 2, H = 4;
+    const path = [
+      [0, 0],
+      [0, 1],
+      [1, 1],
+      [2, 1],
+      [3, 1],
+      [3, 0],
+      [2, 0],
+      [1, 0]
+    ];
+    const frames = [];
+    for (let i = 0; i < path.length; i++) {
+      const g = makeGrid(H, W);
+      g[path[i][0]][path[i][1]] = true;
+      const t1 = (i - 1 + path.length) % path.length;
+      g[path[t1][0]][path[t1][1]] = true;
+      frames.push(gridToBraille(g));
+    }
+    return frames;
+  }
+  function genBreathe() {
+    const stages = [
+      [],
+      [[1, 0]],
+      [[0, 1], [2, 0]],
+      [[0, 0], [1, 1], [3, 0]],
+      [[0, 0], [1, 1], [2, 0], [3, 1]],
+      [[0, 0], [0, 1], [1, 1], [2, 0], [3, 1]],
+      [[0, 0], [0, 1], [1, 0], [2, 1], [3, 0], [3, 1]],
+      [[0, 0], [0, 1], [1, 0], [1, 1], [2, 0], [3, 0], [3, 1]],
+      [[0, 0], [0, 1], [1, 0], [1, 1], [2, 0], [2, 1], [3, 0], [3, 1]]
+    ];
+    const frames = [];
+    const sequence = [...stages, ...stages.slice().reverse().slice(1)];
+    for (const dots of sequence) {
+      const g = makeGrid(4, 2);
+      for (const [r, c] of dots) g[r][c] = true;
+      frames.push(gridToBraille(g));
+    }
+    return frames;
+  }
+  function genWaveRows() {
+    const W = 8, H = 4, totalFrames = 16, frames = [];
+    for (let f = 0; f < totalFrames; f++) {
+      const g = makeGrid(H, W);
+      for (let c = 0; c < W; c++) {
+        const phase = f - c * 0.5;
+        const row = Math.round((Math.sin(phase * 0.8) + 1) / 2 * (H - 1));
+        g[row][c] = true;
+        if (row > 0) g[row - 1][c] = (f + c) % 3 === 0;
+      }
+      frames.push(gridToBraille(g));
+    }
+    return frames;
+  }
+  function genCheckerboard() {
+    const W = 6, H = 4, frames = [];
+    for (let phase = 0; phase < 4; phase++) {
+      const g = makeGrid(H, W);
+      for (let r = 0; r < H; r++) {
+        for (let c = 0; c < W; c++) {
+          if (phase < 2) {
+            g[r][c] = (r + c + phase) % 2 === 0;
+          } else {
+            g[r][c] = (r + c + phase) % 3 === 0;
+          }
+        }
+      }
+      frames.push(gridToBraille(g));
+    }
+    return frames;
+  }
+  function genHelix() {
+    const W = 8, H = 4, totalFrames = 16, frames = [];
+    for (let f = 0; f < totalFrames; f++) {
+      const g = makeGrid(H, W);
+      for (let c = 0; c < W; c++) {
+        const phase = (f + c) * (Math.PI / 4);
+        const y1 = Math.round((Math.sin(phase) + 1) / 2 * (H - 1));
+        const y2 = Math.round((Math.sin(phase + Math.PI) + 1) / 2 * (H - 1));
+        g[y1][c] = true;
+        g[y2][c] = true;
+      }
+      frames.push(gridToBraille(g));
+    }
+    return frames;
+  }
+  function genFillSweep() {
+    const W = 4, H = 4, frames = [];
+    for (let row = H - 1; row >= 0; row--) {
+      const g = makeGrid(H, W);
+      for (let r = row; r < H; r++) {
+        for (let c = 0; c < W; c++) g[r][c] = true;
+      }
+      frames.push(gridToBraille(g));
+    }
+    const full = makeGrid(H, W);
+    for (let r = 0; r < H; r++) for (let c = 0; c < W; c++) full[r][c] = true;
+    frames.push(gridToBraille(full));
+    frames.push(gridToBraille(full));
+    for (let row = 0; row < H; row++) {
+      const g = makeGrid(H, W);
+      for (let r = row + 1; r < H; r++) {
+        for (let c = 0; c < W; c++) g[r][c] = true;
+      }
+      frames.push(gridToBraille(g));
+    }
+    frames.push(gridToBraille(makeGrid(H, W)));
+    return frames;
+  }
+  function genDiagonalSwipe() {
+    const W = 4, H = 4, frames = [];
+    const maxDiag = W + H - 2;
+    for (let d = 0; d <= maxDiag; d++) {
+      const g = makeGrid(H, W);
+      for (let r = 0; r < H; r++) {
+        for (let c = 0; c < W; c++) {
+          if (r + c <= d) g[r][c] = true;
+        }
+      }
+      frames.push(gridToBraille(g));
+    }
+    const full = makeGrid(H, W);
+    for (let r = 0; r < H; r++) for (let c = 0; c < W; c++) full[r][c] = true;
+    frames.push(gridToBraille(full));
+    for (let d = 0; d <= maxDiag; d++) {
+      const g = makeGrid(H, W);
+      for (let r = 0; r < H; r++) {
+        for (let c = 0; c < W; c++) {
+          if (r + c > d) g[r][c] = true;
+        }
+      }
+      frames.push(gridToBraille(g));
+    }
+    frames.push(gridToBraille(makeGrid(H, W)));
+    return frames;
+  }
+  var spinners = {
+    // === Classic braille single-char ===
+    braille: {
+      frames: ["\u280B", "\u2819", "\u2839", "\u2838", "\u283C", "\u2834", "\u2826", "\u2827", "\u2807", "\u280F"],
+      interval: 80
+    },
+    braillewave: {
+      frames: [
+        "\u2801\u2802\u2804\u2840",
+        "\u2802\u2804\u2840\u2880",
+        "\u2804\u2840\u2880\u2820",
+        "\u2840\u2880\u2820\u2810",
+        "\u2880\u2820\u2810\u2808",
+        "\u2820\u2810\u2808\u2801",
+        "\u2810\u2808\u2801\u2802",
+        "\u2808\u2801\u2802\u2804"
+      ],
+      interval: 100
+    },
+    dna: {
+      frames: [
+        "\u280B\u2809\u2819\u281A",
+        "\u2809\u2819\u281A\u2812",
+        "\u2819\u281A\u2812\u2802",
+        "\u281A\u2812\u2802\u2802",
+        "\u2812\u2802\u2802\u2812",
+        "\u2802\u2802\u2812\u2832",
+        "\u2802\u2812\u2832\u2834",
+        "\u2812\u2832\u2834\u2824",
+        "\u2832\u2834\u2824\u2804",
+        "\u2834\u2824\u2804\u280B",
+        "\u2824\u2804\u280B\u2809",
+        "\u2804\u280B\u2809\u2819"
+      ],
+      interval: 80
+    },
+    // === Generated braille grid animations ===
+    scan: { frames: genScan(), interval: 70 },
+    rain: { frames: genRain(), interval: 100 },
+    scanline: { frames: genScanLine(), interval: 120 },
+    pulse: { frames: genPulse(), interval: 180 },
+    snake: { frames: genSnake(), interval: 80 },
+    sparkle: { frames: genSparkle(), interval: 150 },
+    cascade: { frames: genCascade(), interval: 60 },
+    columns: { frames: genColumns(), interval: 60 },
+    orbit: { frames: genOrbit(), interval: 100 },
+    breathe: { frames: genBreathe(), interval: 100 },
+    waverows: { frames: genWaveRows(), interval: 90 },
+    checkerboard: { frames: genCheckerboard(), interval: 250 },
+    helix: { frames: genHelix(), interval: 80 },
+    fillsweep: { frames: genFillSweep(), interval: 100 },
+    diagswipe: { frames: genDiagonalSwipe(), interval: 60 }
+  };
+  var braille_default = spinners;
+  return __toCommonJS(braille_exports);
+})();

package/dist/braille.js

@@ -3,7 +3,7 @@ import {
   gridToBraille,
   makeGrid,
   spinners
-} from "./chunk-JW3PMLWA.js";
+} from "./chunk-F2BWZODB.js";
 export {
   braille_default as default,
   gridToBraille,

package/dist/{chunk-JW3PMLWA.js → chunk-F2BWZODB.js}

@@ -29,6 +29,7 @@ function gridToBraille(grid) {
   return result;
 }
 function makeGrid(rows, cols) {
+  if (rows <= 0 || cols <= 0) return [];
   return Array.from({ length: rows }, () => Array(cols).fill(false));
 }
 function genScan() {
@@ -350,24 +351,7 @@ var spinners = {
   checkerboard: { frames: genCheckerboard(), interval: 250 },
   helix: { frames: genHelix(), interval: 80 },
   fillsweep: { frames: genFillSweep(), interval: 100 },
-  diagswipe: { frames: genDiagonalSwipe(), interval: 60 },
-  // === Non-braille classics ===
-  arc: {
-    frames: ["\u25DC", "\u25E0", "\u25DD", "\u25DE", "\u25E1", "\u25DF"],
-    interval: 100
-  },
-  halfmoon: {
-    frames: ["\u25D0", "\u25D3", "\u25D1", "\u25D2"],
-    interval: 180
-  },
-  line: {
-    frames: ["|", "/", "\u2014", "\\"],
-    interval: 100
-  },
-  blocks: {
-    frames: ["\u2581", "\u2582", "\u2583", "\u2584", "\u2585", "\u2586", "\u2587", "\u2588", "\u2587", "\u2586", "\u2585", "\u2584", "\u2583", "\u2582"],
-    interval: 100
-  }
+  diagswipe: { frames: genDiagonalSwipe(), interval: 60 }
 };
 var braille_default = spinners;
 

package/dist/index.cjs

@@ -58,6 +58,7 @@ function gridToBraille(grid) {
   return result;
 }
 function makeGrid(rows, cols) {
+  if (rows <= 0 || cols <= 0) return [];
   return Array.from({ length: rows }, () => Array(cols).fill(false));
 }
 function genScan() {
@@ -379,24 +380,7 @@ var spinners = {
   checkerboard: { frames: genCheckerboard(), interval: 250 },
   helix: { frames: genHelix(), interval: 80 },
   fillsweep: { frames: genFillSweep(), interval: 100 },
-  diagswipe: { frames: genDiagonalSwipe(), interval: 60 },
-  // === Non-braille classics ===
-  arc: {
-    frames: ["\u25DC", "\u25E0", "\u25DD", "\u25DE", "\u25E1", "\u25DF"],
-    interval: 100
-  },
-  halfmoon: {
-    frames: ["\u25D0", "\u25D3", "\u25D1", "\u25D2"],
-    interval: 180
-  },
-  line: {
-    frames: ["|", "/", "\u2014", "\\"],
-    interval: 100
-  },
-  blocks: {
-    frames: ["\u2581", "\u2582", "\u2583", "\u2584", "\u2585", "\u2586", "\u2587", "\u2588", "\u2587", "\u2586", "\u2585", "\u2584", "\u2583", "\u2582"],
-    interval: 100
-  }
+  diagswipe: { frames: genDiagonalSwipe(), interval: 60 }
 };
 var braille_default = spinners;
 // Annotate the CommonJS export names for ESM import in node:

package/dist/index.js

@@ -3,7 +3,7 @@ import {
   gridToBraille,
   makeGrid,
   spinners
-} from "./chunk-JW3PMLWA.js";
+} from "./chunk-F2BWZODB.js";
 export {
   braille_default as default,
   gridToBraille,

package/package.json

@@ -1,16 +1,28 @@
 {
   "name": "unicode-animations",
-  "version": "0.2.1",
+  "version": "1.0.0",
   "description": "Unicode spinner animations as raw frame data",
   "type": "module",
   "exports": {
     ".": {
-      "import": { "types": "./dist/index.d.ts", "default": "./dist/index.js" },
-      "require": { "types": "./dist/index.d.cts", "default": "./dist/index.cjs" }
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
     },
     "./braille": {
-      "import": { "types": "./dist/braille.d.ts", "default": "./dist/braille.js" },
-      "require": { "types": "./dist/braille.d.cts", "default": "./dist/braille.cjs" }
+      "import": {
+        "types": "./dist/braille.d.ts",
+        "default": "./dist/braille.js"
+      },
+      "require": {
+        "types": "./dist/braille.d.cts",
+        "default": "./dist/braille.cjs"
+      }
     }
   },
   "bin": {
@@ -19,10 +31,14 @@
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
-  "files": ["dist", "scripts"],
+  "files": [
+    "dist",
+    "scripts"
+  ],
   "sideEffects": false,
   "scripts": {
     "build": "tsup",
+    "test": "vitest run",
     "postinstall": "node scripts/postinstall.cjs",
     "prepublishOnly": "npm run build"
   },
@@ -31,10 +47,19 @@
     "url": "git+https://github.com/gunnargray-dev/unicode-animations.git"
   },
   "homepage": "https://github.com/gunnargray-dev/unicode-animations",
-  "keywords": ["braille", "spinner", "unicode", "animation", "loading", "cli", "terminal"],
+  "keywords": [
+    "braille",
+    "spinner",
+    "unicode",
+    "animation",
+    "loading",
+    "cli",
+    "terminal"
+  ],
   "license": "MIT",
   "devDependencies": {
     "tsup": "^8.4.0",
-    "typescript": "^5.7.0"
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
   }
 }

package/scripts/demo.cjs

@@ -34,7 +34,7 @@ if (!out.isTTY) {
     out = new tty.WriteStream(fd);
   } catch {
     // Fallback: no TTY available, just list and exit
-    console.log('22 spinners: ' + names.join(', '));
+    console.log('18 spinners: ' + names.join(', '));
     process.exit(0);
   }
 }
@@ -51,9 +51,23 @@ const cleanup = () => { try { out.write(show); } catch {} };
 process.on('SIGINT', () => { cleanup(); out.write('\n'); process.exit(0); });
 process.on('exit', cleanup);
 
+// Enable raw mode so keypresses (q, Ctrl+C, Esc) are caught immediately
+if (process.stdin.isTTY) {
+  process.stdin.setRawMode(true);
+  process.stdin.resume();
+  process.stdin.on('data', (key) => {
+    // q, Ctrl+C, or Escape
+    if (key[0] === 0x71 || key[0] === 0x03 || key[0] === 0x1B) {
+      cleanup();
+      out.write('\n');
+      process.exit(0);
+    }
+  });
+}
+
 if (args[0] === '--list' || args[0] === '-l') {
   cleanup();
-  out.write(`\n${bold}22 spinners available:${reset}\n\n`);
+  out.write(`\n${bold}18 spinners available:${reset}\n\n`);
   for (const name of names) {
     const s = S[name];
     out.write(`  ${magenta}${s.frames[0]}${reset}  ${name} ${dim}(${s.frames.length} frames, ${s.interval}ms)${reset}\n`);

package/scripts/demo.html

@@ -155,6 +155,59 @@
     }
     footer a { color: var(--accent); text-decoration: none; }
     footer a:hover { text-decoration: underline; }
+
+    .prose {
+      font-size: 0.9rem;
+      line-height: 1.7;
+      color: var(--text-2);
+      margin-bottom: 1rem;
+    }
+    .prose code, .sub-label code, .ref-table code {
+      font-family: var(--mono);
+      font-size: 0.8rem;
+      background: var(--surface);
+      border: 1px solid var(--border);
+      border-radius: 4px;
+      padding: 0.15rem 0.4rem;
+    }
+    .ref-table code { font-size: 0.75rem; }
+
+    .doc-section {
+      margin-top: 3rem;
+    }
+    .doc-section .usage {
+      margin-top: 1rem;
+    }
+
+    .sub-label {
+      font-size: 0.8rem;
+      font-weight: 600;
+      color: var(--text);
+      margin: 1.5rem 0 0.75rem;
+    }
+
+    .ref-table {
+      width: 100%;
+      border-collapse: collapse;
+      font-size: 0.8rem;
+      margin: 1rem 0;
+    }
+    .ref-table th {
+      text-align: left;
+      font-weight: 600;
+      font-size: 0.7rem;
+      text-transform: uppercase;
+      letter-spacing: 0.08em;
+      color: var(--text-3);
+      padding: 0.5rem 0.75rem;
+      border-bottom: 1px solid var(--border);
+    }
+    .ref-table td {
+      padding: 0.5rem 0.75rem;
+      border-bottom: 1px solid var(--border);
+      color: var(--text-2);
+    }
+    .ref-table tr:last-child td { border-bottom: none; }
   </style>
 </head>
 <body>
@@ -194,65 +247,214 @@
 clearInterval(timer)
 process.stdout.write(<span class="str">'\r✔ Done.\n'</span>)</pre>
     </section>
+
+    <section class="doc-section">
+      <div class="section-label">Quick start</div>
+      <div class="usage">
+        <pre><span class="cm">// ESM</span>
+<span class="kw">import</span> spinners <span class="kw">from</span> <span class="str">'unicode-animations'</span>
+
+<span class="cm">// CJS</span>
+<span class="kw">const</span> spinners = require(<span class="str">'unicode-animations'</span>)</pre>
+      </div>
+      <p class="prose">Each spinner is a <code>{ frames: string[], interval: number }</code> object.</p>
+    </section>
+
+    <section class="doc-section">
+      <div class="section-label">Examples</div>
+
+      <div class="sub-label">CLI tool — spinner during async work</div>
+      <div class="usage">
+        <pre><span class="kw">import</span> spinners <span class="kw">from</span> <span class="str">'unicode-animations'</span>
+
+<span class="kw">const</span> { frames, interval } = spinners.braille
+<span class="kw">let</span> i = 0
+
+<span class="kw">const</span> spinner = setInterval(() => {
+  process.stdout.write(<span class="str">`\r\x1B[2K  ${frames[i++ % frames.length]} Deploying...`</span>)
+}, interval)
+
+<span class="kw">await</span> deploy()
+
+clearInterval(spinner)
+process.stdout.write(<span class="str">'\r\x1B[2K  ✔ Deployed.\n'</span>)</pre>
+      </div>
+
+      <div class="sub-label">Reusable spinner helper</div>
+      <div class="usage">
+        <pre><span class="kw">import</span> spinners <span class="kw">from</span> <span class="str">'unicode-animations'</span>
+
+<span class="kw">function</span> createSpinner(msg, name = <span class="str">'braille'</span>) {
+  <span class="kw">const</span> { frames, interval } = spinners[name]
+  <span class="kw">let</span> i = 0, text = msg
+  <span class="kw">const</span> timer = setInterval(() => {
+    process.stdout.write(<span class="str">`\r\x1B[2K  ${frames[i++ % frames.length]} ${text}`</span>)
+  }, interval)
+
+  <span class="kw">return</span> {
+    update(msg) { text = msg },
+    stop(msg) { clearInterval(timer); process.stdout.write(<span class="str">`\r\x1B[2K  ✔ ${msg}\n`</span>) },
+  }
+}
+
+<span class="kw">const</span> s = createSpinner(<span class="str">'Connecting to database...'</span>)
+<span class="kw">const</span> db = <span class="kw">await</span> connect()
+s.update(<span class="str">`Running ${migrations.length} migrations...`</span>)
+<span class="kw">await</span> db.migrate(migrations)
+s.stop(<span class="str">'Database ready.'</span>)</pre>
+      </div>
+
+      <div class="sub-label">Multi-step pipeline</div>
+      <div class="usage">
+        <pre><span class="kw">import</span> spinners <span class="kw">from</span> <span class="str">'unicode-animations'</span>
+
+<span class="kw">async function</span> runWithSpinner(label, fn, name = <span class="str">'braille'</span>) {
+  <span class="kw">const</span> { frames, interval } = spinners[name]
+  <span class="kw">let</span> i = 0
+  <span class="kw">const</span> timer = setInterval(() => {
+    process.stdout.write(<span class="str">`\r\x1B[2K  ${frames[i++ % frames.length]} ${label}`</span>)
+  }, interval)
+  <span class="kw">const</span> result = <span class="kw">await</span> fn()
+  clearInterval(timer)
+  process.stdout.write(<span class="str">`\r\x1B[2K  ✔ ${label}\n`</span>)
+  <span class="kw">return</span> result
+}
+
+<span class="kw">await</span> runWithSpinner(<span class="str">'Linting...'</span>, lint, <span class="str">'scan'</span>)
+<span class="kw">await</span> runWithSpinner(<span class="str">'Running tests...'</span>, test, <span class="str">'helix'</span>)
+<span class="kw">await</span> runWithSpinner(<span class="str">'Building...'</span>, build, <span class="str">'cascade'</span>)
+<span class="kw">await</span> runWithSpinner(<span class="str">'Publishing...'</span>, publish, <span class="str">'braille'</span>)</pre>
+      </div>
+
+      <div class="sub-label">React component</div>
+      <div class="usage">
+        <pre><span class="kw">import</span> { useState, useEffect } <span class="kw">from</span> <span class="str">'react'</span>
+<span class="kw">import</span> spinners <span class="kw">from</span> <span class="str">'unicode-animations'</span>
+
+<span class="kw">function</span> Spinner({ name = <span class="str">'braille'</span>, children }) {
+  <span class="kw">const</span> [frame, setFrame] = useState(0)
+  <span class="kw">const</span> s = spinners[name]
+
+  useEffect(() => {
+    <span class="kw">const</span> timer = setInterval(
+      () => setFrame(f => (f + 1) % s.frames.length),
+      s.interval
+    )
+    <span class="kw">return</span> () => clearInterval(timer)
+  }, [name])
+
+  <span class="kw">return</span> &lt;span style={{ fontFamily: <span class="str">'monospace'</span> }}>{s.frames[frame]} {children}&lt;/span>
+}
+
+<span class="cm">// Usage: &lt;Spinner name="helix">Generating response...&lt;/Spinner></span></pre>
+      </div>
+
+      <div class="sub-label">Browser — status indicator</div>
+      <div class="usage">
+        <pre><span class="kw">import</span> spinners <span class="kw">from</span> <span class="str">'unicode-animations'</span>
+
+<span class="kw">const</span> el = document.getElementById(<span class="str">'status'</span>)
+<span class="kw">const</span> { frames, interval } = spinners.orbit
+<span class="kw">let</span> i = 0
+
+<span class="kw">const</span> spinner = setInterval(() => {
+  el.textContent = <span class="str">`${frames[i++ % frames.length]} Syncing...`</span>
+}, interval)
+
+<span class="kw">await</span> sync()
+clearInterval(spinner)
+el.textContent = <span class="str">'✔ Synced'</span></pre>
+      </div>
+    </section>
+
+    <section class="doc-section">
+      <div class="section-label">All spinners</div>
+
+      <div class="sub-label">Classic braille</div>
+      <table class="ref-table">
+        <thead><tr><th>Name</th><th>Preview</th><th>Interval</th></tr></thead>
+        <tbody>
+          <tr><td><code>braille</code></td><td><code>⠋ ⠙ ⠹ ⠸ ⠼ ⠴ ⠦ ⠧ ⠇ ⠏</code></td><td>80ms</td></tr>
+          <tr><td><code>braillewave</code></td><td><code>⠁⠂⠄⡀</code> → <code>⠂⠄⡀⢀</code></td><td>100ms</td></tr>
+          <tr><td><code>dna</code></td><td><code>⠋⠉⠙⠚</code> → <code>⠉⠙⠚⠒</code></td><td>80ms</td></tr>
+        </tbody>
+      </table>
+
+      <div class="sub-label">Grid animations (braille)</div>
+      <table class="ref-table">
+        <thead><tr><th>Name</th><th>Frames</th><th>Interval</th></tr></thead>
+        <tbody>
+          <tr><td><code>scan</code></td><td>10</td><td>70ms</td></tr>
+          <tr><td><code>rain</code></td><td>12</td><td>100ms</td></tr>
+          <tr><td><code>scanline</code></td><td>6</td><td>120ms</td></tr>
+          <tr><td><code>pulse</code></td><td>5</td><td>180ms</td></tr>
+          <tr><td><code>snake</code></td><td>16</td><td>80ms</td></tr>
+          <tr><td><code>sparkle</code></td><td>6</td><td>150ms</td></tr>
+          <tr><td><code>cascade</code></td><td>12</td><td>60ms</td></tr>
+          <tr><td><code>columns</code></td><td>26</td><td>60ms</td></tr>
+          <tr><td><code>orbit</code></td><td>8</td><td>100ms</td></tr>
+          <tr><td><code>breathe</code></td><td>17</td><td>100ms</td></tr>
+          <tr><td><code>waverows</code></td><td>16</td><td>90ms</td></tr>
+          <tr><td><code>checkerboard</code></td><td>4</td><td>250ms</td></tr>
+          <tr><td><code>helix</code></td><td>16</td><td>80ms</td></tr>
+          <tr><td><code>fillsweep</code></td><td>11</td><td>100ms</td></tr>
+          <tr><td><code>diagswipe</code></td><td>16</td><td>60ms</td></tr>
+        </tbody>
+      </table>
+    </section>
+
+    <section class="doc-section">
+      <div class="section-label">Custom spinners</div>
+      <p class="prose">Create your own braille spinners using the grid utilities:</p>
+      <div class="usage">
+        <pre><span class="kw">import</span> { gridToBraille, makeGrid } <span class="kw">from</span> <span class="str">'unicode-animations'</span>
+
+<span class="cm">// Create a 4-row × 4-col grid</span>
+<span class="kw">const</span> grid = makeGrid(4, 4)
+grid[0][0] = <span class="kw">true</span>
+grid[1][1] = <span class="kw">true</span>
+grid[2][2] = <span class="kw">true</span>
+grid[3][3] = <span class="kw">true</span>
+
+console.log(gridToBraille(grid)) <span class="cm">// diagonal braille pattern</span></pre>
+      </div>
+      <p class="prose"><code>makeGrid(rows, cols)</code> returns a <code>boolean[][]</code>. Set cells to <code>true</code> to raise dots. <code>gridToBraille(grid)</code> converts it to a braille string (2 dot-columns per character).</p>
+    </section>
+
+    <section class="doc-section">
+      <div class="section-label">API</div>
+
+      <div class="sub-label">Spinner</div>
+      <div class="usage">
+        <pre><span class="kw">interface</span> Spinner {
+  <span class="kw">readonly</span> frames: <span class="kw">readonly</span> string[]
+  <span class="kw">readonly</span> interval: number
+}</pre>
+      </div>
+
+      <div class="sub-label">Exports from <code>'unicode-animations'</code></div>
+      <table class="ref-table">
+        <thead><tr><th>Export</th><th>Type</th></tr></thead>
+        <tbody>
+          <tr><td><code>default</code> / <code>spinners</code></td><td><code>Record&lt;BrailleSpinnerName, Spinner></code></td></tr>
+          <tr><td><code>gridToBraille(grid)</code></td><td><code>(boolean[][]) => string</code></td></tr>
+          <tr><td><code>makeGrid(rows, cols)</code></td><td><code>(number, number) => boolean[][]</code></td></tr>
+          <tr><td><code>Spinner</code></td><td>TypeScript interface</td></tr>
+          <tr><td><code>BrailleSpinnerName</code></td><td>Union type of all 18 spinner names</td></tr>
+        </tbody>
+      </table>
+      <p class="prose">The subpath <code>'unicode-animations/braille'</code> re-exports everything from the main entrypoint.</p>
+    </section>
   </main>
 
   <footer>
-    <a href="https://github.com/gunnargray-dev/unicode-animations">GitHub</a>
+    made by <a href="https://x.com/gunnargray">Gunnar Gray</a>
     &nbsp;·&nbsp; MIT License
   </footer>
 
+<script src="../dist/braille.global.js"></script>
 <script>
-// Spinner data (inlined from the package)
-const BRAILLE_DOT_MAP = [[0x01,0x08],[0x02,0x10],[0x04,0x20],[0x40,0x80]];
-function gridToBraille(grid) {
-  const rows = grid.length, cols = grid[0]?.length || 0, cc = Math.ceil(cols / 2);
-  let r = '';
-  for (let c = 0; c < cc; c++) {
-    let code = 0x2800;
-    for (let ri = 0; ri < 4 && ri < rows; ri++)
-      for (let d = 0; d < 2; d++) { const col = c*2+d; if (col < cols && grid[ri]?.[col]) code |= BRAILLE_DOT_MAP[ri][d]; }
-    r += String.fromCodePoint(code);
-  }
-  return r;
-}
-function makeGrid(r,c) { return Array.from({length:r},()=>Array(c).fill(false)); }
-
-function genScan(){const W=8,H=4,f=[];for(let p=-1;p<W+1;p++){const g=makeGrid(H,W);for(let r=0;r<H;r++)for(let c=0;c<W;c++)if(c===p||c===p-1)g[r][c]=true;f.push(gridToBraille(g))}return f}
-function genRain(){const W=8,H=4,n=12,f=[],o=[0,3,1,5,2,7,4,6];for(let i=0;i<n;i++){const g=makeGrid(H,W);for(let c=0;c<W;c++){const r=(i+o[c])%(H+2);if(r<H)g[r][c]=true}f.push(gridToBraille(g))}return f}
-function genScanLine(){const W=6,H=4,f=[],p=[0,1,2,3,2,1];for(const row of p){const g=makeGrid(H,W);for(let c=0;c<W;c++){g[row][c]=true;if(row>0)g[row-1][c]=(c%2===0)}f.push(gridToBraille(g))}return f}
-function genPulse(){const W=6,H=4,f=[],cx=W/2-0.5,cy=H/2-0.5;for(const r of[0.5,1.2,2,3,3.5]){const g=makeGrid(H,W);for(let row=0;row<H;row++)for(let col=0;col<W;col++)if(Math.abs(Math.sqrt((col-cx)**2+(row-cy)**2)-r)<0.9)g[row][col]=true;f.push(gridToBraille(g))}return f}
-function genSnake(){const W=4,H=4,path=[];for(let r=0;r<H;r++)if(r%2===0)for(let c=0;c<W;c++)path.push([r,c]);else for(let c=W-1;c>=0;c--)path.push([r,c]);const f=[];for(let i=0;i<path.length;i++){const g=makeGrid(H,W);for(let t=0;t<4;t++){const idx=(i-t+path.length)%path.length;g[path[idx][0]][path[idx][1]]=true}f.push(gridToBraille(g))}return f}
-function genSparkle(){const ps=[[1,0,0,1,0,0,1,0,0,0,1,0,0,1,0,0,0,1,0,0,1,0,0,1,1,0,0,0,0,1,0,0],[0,1,0,0,1,0,0,1,1,0,0,1,0,0,0,1,0,0,0,1,0,1,0,0,0,0,1,0,1,0,1,0],[0,0,1,0,0,1,0,0,0,1,0,0,0,0,1,0,1,0,1,0,0,0,0,1,0,1,0,1,0,0,0,1],[1,0,0,0,0,0,1,1,0,0,1,0,1,0,0,0,0,0,0,0,1,0,1,0,1,0,0,1,0,0,1,0],[0,0,0,1,1,0,0,0,0,1,0,0,0,1,0,1,1,0,0,1,0,0,0,0,0,1,0,0,0,1,0,1],[0,1,1,0,0,0,0,1,0,0,0,1,0,0,1,0,0,1,0,0,0,1,0,0,0,0,1,0,1,0,0,0]];const W=8,H=4,f=[];for(const p of ps){const g=makeGrid(H,W);for(let r=0;r<H;r++)for(let c=0;c<W;c++)g[r][c]=!!p[r*W+c];f.push(gridToBraille(g))}return f}
-function genCascade(){const W=8,H=4,f=[];for(let o=-2;o<W+H;o++){const g=makeGrid(H,W);for(let r=0;r<H;r++)for(let c=0;c<W;c++)if(c+r===o||c+r===o-1)g[r][c]=true;f.push(gridToBraille(g))}return f}
-function genColumns(){const W=6,H=4,f=[];for(let col=0;col<W;col++)for(let ft=H-1;ft>=0;ft--){const g=makeGrid(H,W);for(let pc=0;pc<col;pc++)for(let r=0;r<H;r++)g[r][pc]=true;for(let r=ft;r<H;r++)g[r][col]=true;f.push(gridToBraille(g))}const full=makeGrid(H,W);for(let r=0;r<H;r++)for(let c=0;c<W;c++)full[r][c]=true;f.push(gridToBraille(full));f.push(gridToBraille(makeGrid(H,W)));return f}
-function genOrbit(){const W=2,H=4,path=[[0,0],[0,1],[1,1],[2,1],[3,1],[3,0],[2,0],[1,0]],f=[];for(let i=0;i<path.length;i++){const g=makeGrid(H,W);g[path[i][0]][path[i][1]]=true;const t=(i-1+path.length)%path.length;g[path[t][0]][path[t][1]]=true;f.push(gridToBraille(g))}return f}
-function genBreathe(){const stages=[[],[[1,0]],[[0,1],[2,0]],[[0,0],[1,1],[3,0]],[[0,0],[1,1],[2,0],[3,1]],[[0,0],[0,1],[1,1],[2,0],[3,1]],[[0,0],[0,1],[1,0],[2,1],[3,0],[3,1]],[[0,0],[0,1],[1,0],[1,1],[2,0],[3,0],[3,1]],[[0,0],[0,1],[1,0],[1,1],[2,0],[2,1],[3,0],[3,1]]];const seq=[...stages,...stages.slice().reverse().slice(1)],f=[];for(const dots of seq){const g=makeGrid(4,2);for(const[r,c]of dots)g[r][c]=true;f.push(gridToBraille(g))}return f}
-function genWaveRows(){const W=8,H=4,n=16,f=[];for(let i=0;i<n;i++){const g=makeGrid(H,W);for(let c=0;c<W;c++){const row=Math.round((Math.sin((i-c*0.5)*0.8)+1)/2*(H-1));g[row][c]=true;if(row>0)g[row-1][c]=(i+c)%3===0}f.push(gridToBraille(g))}return f}
-function genCheckerboard(){const W=6,H=4,f=[];for(let p=0;p<4;p++){const g=makeGrid(H,W);for(let r=0;r<H;r++)for(let c=0;c<W;c++)g[r][c]=p<2?(r+c+p)%2===0:(r+c+p)%3===0;f.push(gridToBraille(g))}return f}
-function genHelix(){const W=8,H=4,n=16,f=[];for(let i=0;i<n;i++){const g=makeGrid(H,W);for(let c=0;c<W;c++){const ph=(i+c)*(Math.PI/4);g[Math.round((Math.sin(ph)+1)/2*(H-1))][c]=true;g[Math.round((Math.sin(ph+Math.PI)+1)/2*(H-1))][c]=true}f.push(gridToBraille(g))}return f}
-function genFillSweep(){const W=4,H=4,f=[];for(let row=H-1;row>=0;row--){const g=makeGrid(H,W);for(let r=row;r<H;r++)for(let c=0;c<W;c++)g[r][c]=true;f.push(gridToBraille(g))}const full=makeGrid(H,W);for(let r=0;r<H;r++)for(let c=0;c<W;c++)full[r][c]=true;f.push(gridToBraille(full));f.push(gridToBraille(full));for(let row=0;row<H;row++){const g=makeGrid(H,W);for(let r=row+1;r<H;r++)for(let c=0;c<W;c++)g[r][c]=true;f.push(gridToBraille(g))}f.push(gridToBraille(makeGrid(H,W)));return f}
-function genDiagSwipe(){const W=4,H=4,f=[],mx=W+H-2;for(let d=0;d<=mx;d++){const g=makeGrid(H,W);for(let r=0;r<H;r++)for(let c=0;c<W;c++)if(r+c<=d)g[r][c]=true;f.push(gridToBraille(g))}const full=makeGrid(H,W);for(let r=0;r<H;r++)for(let c=0;c<W;c++)full[r][c]=true;f.push(gridToBraille(full));for(let d=0;d<=mx;d++){const g=makeGrid(H,W);for(let r=0;r<H;r++)for(let c=0;c<W;c++)if(r+c>d)g[r][c]=true;f.push(gridToBraille(g))}f.push(gridToBraille(makeGrid(H,W)));return f}
-
-const spinners = {
-  braille:{frames:['⠋','⠙','⠹','⠸','⠼','⠴','⠦','⠧','⠇','⠏'],interval:80},
-  braillewave:{frames:['⠁⠂⠄⡀','⠂⠄⡀⢀','⠄⡀⢀⠠','⡀⢀⠠⠐','⢀⠠⠐⠈','⠠⠐⠈⠁','⠐⠈⠁⠂','⠈⠁⠂⠄'],interval:100},
-  dna:{frames:['⠋⠉⠙⠚','⠉⠙⠚⠒','⠙⠚⠒⠂','⠚⠒⠂⠂','⠒⠂⠂⠒','⠂⠂⠒⠲','⠂⠒⠲⠴','⠒⠲⠴⠤','⠲⠴⠤⠄','⠴⠤⠄⠋','⠤⠄⠋⠉','⠄⠋⠉⠙'],interval:80},
-  scan:{frames:genScan(),interval:70},
-  rain:{frames:genRain(),interval:100},
-  scanline:{frames:genScanLine(),interval:120},
-  pulse:{frames:genPulse(),interval:180},
-  snake:{frames:genSnake(),interval:80},
-  sparkle:{frames:genSparkle(),interval:150},
-  cascade:{frames:genCascade(),interval:60},
-  columns:{frames:genColumns(),interval:60},
-  orbit:{frames:genOrbit(),interval:100},
-  breathe:{frames:genBreathe(),interval:100},
-  waverows:{frames:genWaveRows(),interval:90},
-  checkerboard:{frames:genCheckerboard(),interval:250},
-  helix:{frames:genHelix(),interval:80},
-  fillsweep:{frames:genFillSweep(),interval:100},
-  diagswipe:{frames:genDiagSwipe(),interval:60},
-};
+const spinners = UnicodeAnimations.spinners;
 
 // Build grid
 const grid = document.getElementById('spinnerGrid');

package/scripts/postinstall.cjs

@@ -7,6 +7,9 @@ const path = require('path');
 const ci = process.env.CI || process.env.CONTINUOUS_INTEGRATION || process.env.GITHUB_ACTIONS;
 if (ci) process.exit(0);
 
+// Skip postinstall when run via npx (temporary install for CLI usage)
+if (__dirname.includes('_npx')) process.exit(0);
+
 let out;
 try {
   const fd = fs.openSync('/dev/tty', 'w');
@@ -28,82 +31,130 @@ try {
   const DURATION = 3000;
   const INTERVAL = 80;
 
-  const d = '\x1B[2m';
-  const b = '\x1B[1m';
-  const r = '\x1B[0m';
-  const c = '\x1B[36m';
-  const g = '\x1B[32m';
-  const w = '\x1B[37m';
-  const m = '\x1B[35m';
-  const hide = '\x1B[?25l';
-  const show = '\x1B[?25h';
-
-  out.write(hide);
-  const cleanup = () => { try { out.write(show); } catch {} };
+  const B = '\x1B[1m';
+  const D = '\x1B[2m';
+  const R = '\x1B[0m';
+  const HIDE = '\x1B[?25l';
+  const SHOW = '\x1B[?25h';
+
+  out.write(HIDE);
+  const cleanup = () => { try { out.write(SHOW); } catch {} };
   process.on('SIGINT', () => { cleanup(); process.exit(0); });
 
-  // Header
-  out.write(`
-${b}${w}  ██╗   ██╗███╗   ██╗██╗ ██████╗ ██████╗ ██████╗ ███████╗${r}
-${b}${w}  ██║   ██║████╗  ██║██║██╔════╝██╔═══██╗██╔══██╗██╔════╝${r}
-${b}${w}  ██║   ██║██╔██╗ ██║██║██║     ██║   ██║██║  ██║█████╗${r}
-${b}${w}  ██║   ██║██║╚██╗██║██║██║     ██║   ██║██║  ██║██╔══╝${r}
-${b}${w}  ╚██████╔╝██║ ╚████║██║╚██████╗╚██████╔╝██████╔╝███████╗${r}
-${d}   ╚═════╝ ╚═╝  ╚═══╝╚═╝ ╚═════╝ ╚═════╝ ╚═════╝ ╚══════╝${r}
-${b}${c}      b r a i l l e   a n i m a t i o n s${r}
-
-`);
-
-  // Braille spinners only, 2 columns of 9
-  const left = [
-    ['Braille',    S.braille],
-    ['Orbit',      S.orbit],
-    ['Breathe',    S.breathe],
-    ['Snake',      S.snake],
-    ['Fill Sweep', S.fillsweep],
-    ['Diag Swipe', S.diagswipe],
-    ['Pulse',      S.pulse],
-    ['Scanline',   S.scanline],
-    ['Columns',    S.columns],
-  ];
+  // Narrow terminal fallback
+  const termCols = out.columns || 80;
+  if (termCols < 60) {
+    out.write(`\n  ${B}unicode-animations${R} ${D}— 18 braille spinners${R}\n\n`);
+    cleanup();
+    return;
+  }
 
-  const right = [
-    ['Checkerboard', S.checkerboard],
-    ['Scan',         S.scan],
-    ['Rain',         S.rain],
-    ['Sparkle',      S.sparkle],
-    ['Cascade',      S.cascade],
-    ['Wave Rows',    S.waverows],
-    ['Helix',        S.helix],
-    ['Braille Wave', S.braillewave],
-    ['DNA',          S.dna],
-  ];
+  function pad(str, n) { return str + ' '.repeat(Math.max(0, n - str.length)); }
 
-  const ROWS = left.length;
+  // ─── Title (box-drawing art) ───
+  const titleLines = [
+    '██╗   ██╗███╗   ██╗██╗ ██████╗ ██████╗ ██████╗ ███████╗',
+    '██║   ██║████╗  ██║██║██╔════╝██╔═══██╗██╔══██╗██╔════╝',
+    '██║   ██║██╔██╗ ██║██║██║     ██║   ██║██║  ██║█████╗  ',
+    '██║   ██║██║╚██╗██║██║██║     ██║   ██║██║  ██║██╔══╝  ',
+    '╚██████╔╝██║ ╚████║██║╚██████╗╚██████╔╝██████╔╝███████╗',
+    ' ╚═════╝ ╚═╝  ╚═══╝╚═╝ ╚═════╝ ╚═════╝ ╚═════╝ ╚══════╝',
+  ];
+  const titleW = 57;
+
+  // ─── Spinner grid: 3 cols × 6 rows ───
+  const layout = [
+    ['braille',   'scan',         'rain'],
+    ['orbit',     'pulse',        'sparkle'],
+    ['breathe',   'cascade',      'waverows'],
+    ['snake',     'columns',      'helix'],
+    ['fillsweep', 'scanline',     'braillewave'],
+    ['diagswipe', 'checkerboard', 'dna'],
+  ];
+  const NPAD = 13;
+
+  // Compute max frame width per column for consistent spacing
+  const colFPad = [0, 1, 2].map(c => {
+    let max = 0;
+    for (const row of layout) {
+      const sp = S[row[c]];
+      for (const f of sp.frames) max = Math.max(max, [...f].length);
+    }
+    return max;
+  });
+  const GRID_W = colFPad.reduce((sum, fp) => sum + fp + 1 + NPAD, 0) + 4;
+  const CONTENT_W = Math.max(GRID_W, titleW) + 4;
+
+  // ─── Crop marks ───
+  const ARM = 1;
+  const inner = Math.max(0, CONTENT_W - 2 - ARM * 2);
+  const cropPad = '  ';
+  const topCrop  = cropPad + '\u280F' + '\u2809'.repeat(ARM) + ' '.repeat(inner) + '\u2809'.repeat(ARM) + '\u28B9';
+  const botCrop  = cropPad + '\u28C7' + '\u28C0'.repeat(ARM) + ' '.repeat(inner) + '\u28C0'.repeat(ARM) + '\u28F8';
+
+  // Center each element within the crop frame
+  function centerPad(w) {
+    return cropPad + ' '.repeat(Math.max(0, Math.floor((CONTENT_W - w) / 2)));
+  }
+  // Left-align all content to the same column, centered as a block within crops
+  const contentW = Math.max(GRID_W, titleW);
+  const contentPad = cropPad + ' '.repeat(Math.max(0, Math.floor((CONTENT_W - contentW) / 2)));
 
-  function pad(str, n) { return str + ' '.repeat(Math.max(0, n - str.length)); }
+  // ─── Render spinner grid ───
+  const ROWS = layout.length;
 
   function renderGrid(tick) {
     let buf = '';
-    for (let i = 0; i < ROWS; i++) {
-      const [ln, ls] = left[i];
-      const [rn, rs] = right[i];
-      const lf = ls.frames[tick % ls.frames.length];
-      const rf = rs.frames[tick % rs.frames.length];
-      buf += `    ${m}${pad(lf, 3)}${r}  ${d}${pad(ln, 12)}${r}  ${m}${pad(rf, 12)}${r}  ${d}${rn}${r}\n`;
+    for (const row of layout) {
+      let line = contentPad;
+      for (let c = 0; c < 3; c++) {
+        const name = row[c];
+        const sp = S[name];
+        const frame = sp.frames[tick % sp.frames.length];
+        line += B + pad(frame, colFPad[c]) + R + ' ' + D + pad(name, NPAD) + R;
+        if (c < 2) line += '  ';
+      }
+      buf += line + '\n';
     }
     return buf;
   }
 
+  // ─── Print static top ───
+  let top = '\n';
+  top += topCrop + '\n';
+  top += '\n';
+  for (let i = 0; i < titleLines.length; i++) {
+    const style = i === titleLines.length - 1 ? D : B;
+    top += contentPad + style + titleLines[i] + R + '\n';
+  }
+  top += contentPad + D + 'BRAILLE ANIMATIONS' + R + '\n';
+  top += '\n';
+  out.write(top);
+
+  // ─── Print first frame of spinners ───
   out.write(renderGrid(0));
 
+  // ─── Animate ───
   let tick = 1;
   const start = Date.now();
 
   const timer = setInterval(() => {
     if (Date.now() - start >= DURATION) {
       clearInterval(timer);
-      out.write(`\n  ${g}${b}✔${r} ${b}unicode-animations${r} ${d}— 18 braille spinners + 4 classics${r}\n\n`);
+      // Print static bottom
+      let bot = '\n';
+      const cmds = [
+        ['npx unicode-animations',        'demo all spinners'],
+        ['npx unicode-animations --list',  'list all spinners'],
+        ['npx unicode-animations --web',   'open in browser'],
+      ];
+      for (const [left, right] of cmds) {
+        const gap = ' '.repeat(Math.max(2, contentW - left.length - right.length));
+        bot += contentPad + D + left + R + gap + D + right + R + '\n';
+      }
+      bot += '\n';
+      bot += botCrop + '\n\n';
+      out.write(bot);
       cleanup();
       return;
     }
@@ -111,6 +162,7 @@ ${b}${c}      b r a i l l e   a n i m a t i o n s${r}
     out.write(renderGrid(tick));
     tick++;
   }, INTERVAL);
+
 } catch {
   try { out.write('\x1B[?25h'); } catch {}
   process.exit(0);