@graedenn/pi-loader 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Graeden
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,136 @@
+# pi-loader ⠿
+
+**Braille-dot working indicator for pi coding agent.**
+
+Replaces the default spinner with rich 2-character braille animations. 54+ patterns including helixes, neural flickers, sweeps, snakes, and more — all in pure ASCII-compatible Unicode braille.
+
+![preview](https://img.shields.io/badge/patterns-54+-brightgreen)
+![license](https://img.shields.io/badge/license-MIT-blue)
+
+![pi-loader demo](demo/pi-loader-demo.gif)
+
+> *Demo: preview gallery, pattern switching, speed & color controls*
+
+## Installation
+
+### Via pi (recommended)
+
+```bash
+pi install npm:@graedenn/pi-loader
+```
+
+Then `/reload` or restart pi.
+
+### Manual
+
+```bash
+mkdir -p ~/.pi/agent/extensions/pi-loader
+cp index.ts patterns.ts ~/.pi/agent/extensions/pi-loader/
+/reload
+```
+
+## Usage
+
+| Command | Description |
+|---|---|
+| `/loader pattern <name>` | Switch animation pattern |
+| `/loader color <color>` | Set color (name, `#hex`, or `0-255` ANSI) |
+| `/loader speed <n>` | Set speed multiplier (0.25–10.0) |
+| `/loader preview` | Interactive gallery with live preview |
+| `/loader reset` | Restore defaults |
+| `/loader off` / `on` | Disable / re-enable |
+
+### Preview mode
+
+`/loader preview` opens an interactive picker:
+
+| Key | Action |
+|---|---|
+| `←` `→` | Switch pattern |
+| `↑` `↓` | Adjust speed |
+| `[` `]` | Cycle color |
+| `Enter` | Select and apply |
+| `Esc` | Close |
+
+Named colors: `accent`, `muted`, `dim`, `text`, `success`, `warning`, `error`, `border`, `borderAccent`
+
+## All Patterns
+
+<details>
+<summary>Click to expand (54+ patterns)</summary>
+
+| Key | Name | Frames |
+|---|---|---|
+| `default` | Default | 10 |
+| `single-dots` | Single Dots | 8 |
+| `single-bounce` | Single Bounce | 14 |
+| `single-fill` | Single Fill | 14 |
+| `single-sweep` | Single Sweep | 8 |
+| `half-helix` | Half Helix | 16 |
+| `helix-core` | Helix Core | 12 |
+| `helix-glow` | Helix Glow | 20 |
+| `thought-helix` | Thought Helix | 19 |
+| `pulse-ladder` | Pulse Ladder | 16 |
+| `core-spiral` | Core Spiral | 16 |
+| `twin-orbit` | Twin Orbit | 16 |
+| `infinity-run` | Infinity Run | 20 |
+| `radar-arc` | Radar Arc | 20 |
+| `scan` | Scan | 6 |
+| `sweep` | Sweep | 13 |
+| `agent-sweep` | Agent Sweep | 19 |
+| `sound-bars` | Sound Bars | 16 |
+| `perimeter-spin-light` | Perimeter Spin Light | 12 |
+| `perimeter-spin` | Perimeter Spin | 12 |
+| `perimeter-spin-bold` | Perimeter Spin Bold | 12 |
+| `shuffle` | Shuffle | 7 |
+| `hangtime` | Hangtime | 57 |
+| `line-spin` | Line Spin | 8 |
+| `ray-spin` | Ray Spin | 8 |
+| `rotating-x` | Rotating X | 4 |
+| `texture-flip` | Texture Flip | 2 |
+| `neural-flicker` | Neural Flicker | 15 |
+| `neural-flicker-chaos` | Neural Flicker Chaos | 43 |
+| `neural-flicker-drift` | Neural Flicker Drift | 41 |
+| `neural-flicker-thought` | Neural Flicker Thought | 41 |
+| `neural-scatter` | Neural Scatter | 16 |
+| `neural-spike` | Neural Spike | 14 |
+| `neural-random-walk` | Neural Random Walk | 16 |
+| `neural-cross-spark` | Neural Cross Spark | 14 |
+| `neural-offset` | Neural Offset | 14 |
+| `neural-braid` | Neural Braid | 18 |
+| `thinking-pulse` | Thinking Pulse | 21 |
+| `soft-thinking` | Soft Thinking | 16 |
+| `deep-thought` | Deep Thought | 23 |
+| `signal-search` | Signal Search | 15 |
+| `binary-thought` | Binary Thought | 13 |
+| `center-spark` | Center Spark | 12 |
+| `synapse-wave` | Synapse Wave | 20 |
+| `inner-current` | Inner Current | 13 |
+| `bouncing-block` | Bouncing Block | 12 |
+| `face` | Smiley Face | 6 |
+| `snake-crawl` | Snake Crawl | 30 |
+| `snake-loop` | Snake Loop | 24 |
+| `circle` | Circle | 6 |
+| `square` | Square | 2 |
+| `twinkle` | Twinkle | 2 |
+| `corners` | Corners | 4 |
+| `growth` | Growth | 10 |
+
+</details>
+
+## Adding Patterns
+
+Add new patterns in `patterns.ts` as `type: "raw"` entries. Each frame is 1–2 braille characters. Use `braille-chars.txt` as a reference for encoding.
+
+```ts
+"my-pattern": {
+  type: "raw",
+  name: "My Pattern",
+  frames: ["⠋⠙", "⠹⠸", "⠼⠴"],
+  defaultSpeed: 1.0
+}
+```
+
+## License
+
+MIT

package/braille-chars.txt

@@ -0,0 +1,75 @@
+BRAILLE CHARACTER REFERENCE for pi-loader (4×4 braille dot loader)
+=========================================================
+
+Each loader frame is 2 braille characters, side by side.
+The left char encodes columns 0-1, the right char encodes columns 2-3.
+
+DOT NUMBERING (within one 2×4 cell):
+    ┌───┬───┐
+    │ 0 │ 3 │
+    ├───┼───┤
+    │ 1 │ 4 │
+    ├───┼───┤
+    │ 2 │ 5 │
+    ├───┼───┤
+    │ 6 │ 7 │
+    └───┴───┘
+
+To compute a character: String.fromCodePoint(0x2800 + sum_of_dot_numbers)
+
+Rows 0-3 = dots 0,1,2,6 (left column) and 3,4,5,7 (right column)
+in the final 2-char frame.
+
+─────────────────────────────────────────────────────────
+
+NO DOTS 6 or 7 (U+2800 - U+283F):
+
+   ⠀  ⠁  ⠂  ⠃  ⠄  ⠅  ⠆  ⠇  ⠈  ⠉  ⠊  ⠋  ⠌  ⠍  ⠎  ⠏
+   ⠐  ⠑  ⠒  ⠓  ⠔  ⠕  ⠖  ⠗  ⠘  ⠙  ⠚  ⠛  ⠜  ⠝  ⠞  ⠟
+   ⠠  ⠡  ⠢  ⠣  ⠤  ⠥  ⠦  ⠧  ⠨  ⠩  ⠪  ⠫  ⠬  ⠭  ⠮  ⠯
+   ⠰  ⠱  ⠲  ⠳  ⠴  ⠵  ⠶  ⠷  ⠸  ⠹  ⠺  ⠻  ⠼  ⠽  ⠾  ⠿
+
+DOT 6 ONLY (U+2840 - U+287F):
+
+   ⡀  ⡁  ⡂  ⡃  ⡄  ⡅  ⡆  ⡇  ⡈  ⡉  ⡊  ⡋  ⡌  ⡍  ⡎  ⡏
+   ⡐  ⡑  ⡒  ⡓  ⡔  ⡕  ⡖  ⡗  ⡘  ⡙  ⡚  ⡛  ⡜  ⡝  ⡞  ⡟
+   ⡠  ⡡  ⡢  ⡣  ⡤  ⡥  ⡦  ⡧  ⡨  ⡩  ⡪  ⡫  ⡬  ⡭  ⡮  ⡯
+   ⡰  ⡱  ⡲  ⡳  ⡴  ⡵  ⡶  ⡷  ⡸  ⡹  ⡺  ⡻  ⡼  ⡽  ⡾  ⡿
+
+DOT 7 ONLY (U+2880 - U+28BF):
+
+   ⢀  ⢁  ⢂  ⢃  ⢄  ⢅  ⢆  ⢇  ⢈  ⢉  ⢊  ⢋  ⢌  ⢍  ⢎  ⢏
+   ⢐  ⢑  ⢒  ⢓  ⢔  ⢕  ⢖  ⢗  ⢘  ⢙  ⢚  ⢛  ⢜  ⢝  ⢞  ⢟
+   ⢠  ⢡  ⢢  ⢣  ⢤  ⢥  ⢦  ⢧  ⢨  ⢩  ⢪  ⢫  ⢬  ⢭  ⢮  ⢯
+   ⢰  ⢱  ⢲  ⢳  ⢴  ⢵  ⢶  ⢷  ⢸  ⢹  ⢺  ⢻  ⢼  ⢽  ⢾  ⢿
+
+DOTS 6+7 (U+28C0 - U+28FF):
+
+   ⣀  ⣁  ⣂  ⣃  ⣄  ⣅  ⣆  ⣇  ⣈  ⣉  ⣊  ⣋  ⣌  ⣍  ⣎  ⣏
+   ⣐  ⣑  ⣒  ⣓  ⣔  ⣕  ⣖  ⣗  ⣘  ⣙  ⣚  ⣛  ⣜  ⣝  ⣞  ⣟
+   ⣠  ⣡  ⣢  ⣣  ⣤  ⣥  ⣦  ⣧  ⣨  ⣩  ⣪  ⣫  ⣬  ⣭  ⣮  ⣯
+   ⣰  ⣱  ⣲  ⣳  ⣴  ⣵  ⣶  ⣷  ⣸  ⣹  ⣺  ⣻  ⣼  ⣽  ⣾  ⣿
+
+─────────────────────────────────────────────────────────
+
+HOW TO BUILD A FRAME:
+
+Your loader shows 2 braille chars = your 4×4 grid.
+
+Left char = columns 0-1 of your grid
+Right char = columns 2-3 of your grid
+
+For the left char, ON dots are:
+  dot 0 = row0 col0    dot 3 = row0 col1
+  dot 1 = row1 col0    dot 4 = row1 col1
+  dot 2 = row2 col0    dot 5 = row2 col1
+  dot 6 = row3 col0    dot 7 = row3 col1
+
+For the right char, same but for columns 2-3.
+
+Find the char above that matches your ON dots, put them together:
+  frame = leftChar + rightChar   (e.g. "⡱⢎")
+
+Then register as a raw pattern:
+  "my-pattern": { type: "raw", name: "My Pattern",
+    frames: ["⡱⢎", "⢎⡱", ...], defaultSpeed: 1.0 },

package/index.ts

@@ -0,0 +1,417 @@
+/**
+ * pi-loader — Braille-dot working indicator for pi coding agent
+ *
+ * Compact braille-dot working indicator inspired by dotmatrix.zzzzshawn.cloud.
+ * Replaces the default spinner with 2-character braille animation.
+ * 54+ configurable patterns.
+ *
+ * Commands (with autocomplete):
+ *   /loader pattern <name>  - Switch pattern
+ *   /loader color <color>            - Set color (name, #hex, or 0-255 ANSI)
+ *   /loader preview [name]      - Preview animation (Esc close, ←→ pattern, ↑↓ color)
+ *   /loader speed <n>           - Set speed multiplier (0.25-10.0)
+ *   /loader reset           - Reset to defaults
+ */
+
+import type { AutocompleteItem } from "@earendil-works/pi-tui";
+import { matchesKey } from "@earendil-works/pi-tui";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+const fs = require("fs");
+const path = require("path");
+
+const cycle = <T>(arr: readonly T[], idx: number, dir: -1 | 1): T =>
+  arr[(idx + dir + arr.length) % arr.length]!;
+
+const COLORS = ["accent", "muted", "dim", "text", "success", "warning", "error", "border", "borderAccent"] as const;
+const PREVIEW_COLORS = [...COLORS, "16","39","48","117","123","183","193","202","213","214","228","244","255"] as string[];
+
+function intervalMs(frameCount: number, defaultSpeed: number, speedMultiplier: number): number {
+  return Math.max(80, Math.min(300, 1600 / frameCount)) / (defaultSpeed * speedMultiplier);
+}
+
+function colorize(text: string, color: string, theme: { fg: (c: string, t: string) => string }): string {
+  if ((COLORS as readonly string[]).includes(color)) return theme.fg(color, text);
+  if (/^#[0-9a-fA-F]{6}$/.test(color)) {
+    const r = parseInt(color.slice(1, 3), 16);
+    const g = parseInt(color.slice(3, 5), 16);
+    const b = parseInt(color.slice(5, 7), 16);
+    return `\x1b[38;2;${r};${g};${b}m${text}\x1b[0m`;
+  }
+  if (/^\d{1,3}$/.test(color)) {
+    const n = parseInt(color, 10);
+    if (n >= 0 && n <= 255) return `\x1b[38;5;${n}m${text}\x1b[0m`;
+  }
+  return text;
+}
+
+// ─── Patterns ──────────────────────────────────────────────────────────
+
+import { PATTERNS, PATTERN_KEYS } from "./patterns";
+
+// ─── Preview component ────────────────────────────────────────────────
+
+class LoaderPreviewComponent {
+  private animInterval: ReturnType<typeof setInterval> | null = null;
+  private frameIndex = 0;
+  private frames: string[] = [];
+  private theme: { fg: (c: string, t: string) => string };
+  private tui: { requestRender: () => void };
+  private done: () => void;
+  private patternIndex: number;
+  private patternKeys: string[];
+  private color: string;
+  private colorValues: string[];
+  private speed: number;
+  private onSelect: (pattern: string, color: string, speed: number) => void;
+
+  constructor(
+    tui: { requestRender: () => void },
+    theme: { fg: (c: string, t: string) => string },
+    done: () => void,
+    startIndex: number,
+    patternKeys: string[],
+    color: string,
+    colorValues: string[],
+    startSpeed: number,
+    onSelect: (pattern: string, color: string, speed: number) => void,
+  ) {
+    this.tui = tui;
+    this.theme = theme;
+    this.done = done;
+    this.patternIndex = startIndex;
+    this.patternKeys = patternKeys;
+    this.color = color;
+    this.colorValues = colorValues;
+    this.speed = startSpeed;
+    this.onSelect = onSelect;
+    this.buildFrames();
+    this.startAnimation();
+  }
+
+  private get patternKey(): string {
+    return this.patternKeys[this.patternIndex]!;
+  }
+
+  private buildFrames(): void {
+    const key = this.patternKey;
+    const entry = PATTERNS[key];
+    if (!entry) {
+      console.error("[loader] unknown pattern:", key, "keys:", Object.keys(PATTERNS).slice(0,5));
+      this.frames = ["⠿"];
+      return;
+    }
+    this.frames = entry.frames.map((f) => colorize(f, this.color, this.theme));
+    this.frameIndex = 0;
+  }
+
+  private startAnimation(): void {
+    this.stopAnimation();
+    const entry = PATTERNS[this.patternKey];
+    if (!entry) return;
+    const ms = intervalMs(this.frames.length, entry.defaultSpeed, this.speed);
+    this.animInterval = setInterval(() => {
+      this.frameIndex = (this.frameIndex + 1) % this.frames.length;
+      this.tui.requestRender();
+    }, Math.max(16, ms));
+  }
+
+  private stopAnimation(): void {
+    if (this.animInterval) { clearInterval(this.animInterval); this.animInterval = null; }
+  }
+
+  private close(): void {
+    this.stopAnimation();
+    this.done();
+  }
+
+  private switchPattern(dir: -1 | 1): void {
+    this.patternIndex = (this.patternIndex + dir + this.patternKeys.length) % this.patternKeys.length;
+    this.buildFrames();
+    this.startAnimation();
+    this.tui.requestRender();
+  }
+
+  private switchColor(dir: -1 | 1): void {
+    this.color = cycle(this.colorValues, this.colorValues.indexOf(this.color), dir);
+    this.buildFrames();
+    this.tui.requestRender();
+  }
+
+  private switchSpeed(dir: -1 | 1): void {
+    this.speed = Math.max(0.25, Math.min(10.0, this.speed + dir * 0.25));
+    this.startAnimation();
+    this.tui.requestRender();
+  }
+
+  render(width: number): string[] {
+    const frame = this.frames[this.frameIndex] ?? this.frames[0] ?? "⠿";
+    const entry = PATTERNS[this.patternKey];
+    const total = this.patternKeys.length;
+    const a = (s: string) => this.theme.fg("accent", s);
+    const d = (s: string) => this.theme.fg("dim", s);
+    const padded = (s: string) => s + " ".repeat(Math.max(0, width - s.length - 4));
+
+    const lines: string[] = [];
+    const hr = a("".padEnd(width, "─"));
+    lines.push(hr);
+    lines.push(" ".repeat(width));
+    lines.push(padded("  " + a("Loader Gallery")));
+    lines.push(" ".repeat(width));
+    lines.push(padded("    " + frame));
+    lines.push(" ".repeat(width));
+    lines.push(padded("  " + (entry?.name ?? this.patternKey)));
+    lines.push(padded("  " + d(`${this.patternIndex + 1} / ${total}  ·  ${this.color}  ·  ${this.speed.toFixed(1)}x`)));
+    lines.push(" ".repeat(width));
+    lines.push(padded("  " + d("[Enter] select  [Esc] close")));
+    lines.push(padded("  " + d("[←→] pattern  [↑↓] speed  [[] ] color")));
+    lines.push(" ".repeat(width));
+    lines.push(hr);
+
+    return lines;
+  }
+
+  handleInput(data: string): void {
+    if (matchesKey(data, "escape")) { this.close(); return; }
+    if (matchesKey(data, "enter")) {
+      this.onSelect(this.patternKey, this.color, this.speed);
+      this.close();
+      return;
+    }
+    if (matchesKey(data, "left")) { this.switchPattern(-1); return; }
+    if (matchesKey(data, "right")) { this.switchPattern(1); return; }
+    if (matchesKey(data, "up")) { this.switchSpeed(1); return; }
+    if (matchesKey(data, "down")) { this.switchSpeed(-1); return; }
+    if (matchesKey(data, "[") || matchesKey(data, "{")) { this.switchColor(-1); return; }
+    if (matchesKey(data, "]") || matchesKey(data, "}")) { this.switchColor(1); return; }
+  }
+
+  invalidate(): void {
+    this.buildFrames();
+  }
+}
+
+// ─── Extension ─────────────────────────────────────────────────────────
+
+interface Config {
+  pattern: string;
+  color: string;
+  speed: number;
+}
+
+const DEFAULTS: Config = {
+  pattern: "default",
+  color: "accent",
+  speed: 1.0,
+};
+
+const CONFIG_PATH = (process.env.HOME || process.env.USERPROFILE || "/tmp") +
+  "/.pi/agent/extensions/pi-loader/config.json";
+
+function loadConfig(): Config {
+  try {
+    const raw = fs.readFileSync(CONFIG_PATH, "utf-8");
+    return { ...DEFAULTS, ...JSON.parse(raw) };
+  } catch (e) {
+    const err = e as { code?: string };
+    if (err.code !== "ENOENT") console.error("[loader] loadConfig error:", e);
+    return { ...DEFAULTS };
+  }
+}
+
+function saveConfig(cfg: Config): void {
+  try {
+    const dir = path.dirname(CONFIG_PATH);
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(CONFIG_PATH, JSON.stringify(cfg, null, 2), "utf-8");
+  } catch (e) {
+    console.error("[loader] saveConfig failed:", e);
+  }
+}
+
+export default function (pi: ExtensionAPI) {
+  let config: Config = loadConfig();
+  let disabled = false;
+
+  const apply = (ctx: ExtensionContext) => {
+    if (disabled) { ctx.ui.setWorkingIndicator(); return; }
+    const pattern = PATTERNS[config.pattern];
+    if (!pattern || !pattern.frames.length) return;
+    ctx.ui.setWorkingIndicator({
+      frames: pattern.frames.map((f) => colorize(f, config.color, ctx.ui.theme)),
+      intervalMs: intervalMs(pattern.frames.length, pattern.defaultSpeed, config.speed),
+    });
+  };
+
+  pi.on("session_start", async (_event, ctx) => {
+    config = loadConfig();
+    apply(ctx);
+  });
+
+  pi.on("before_agent_start", async (_event, ctx) => {
+    apply(ctx);
+  });
+
+  pi.registerCommand("loader", {
+    description: "Configure pi-loader (pattern, color, speed)",
+    getArgumentCompletions: (prefix: string): AutocompleteItem[] | null => {
+      const subs: AutocompleteItem[] = [
+        { value: "preview ", label: "preview — pick pattern/color/speed" },
+        { value: "pattern ", label: "pattern — switch animation" },
+        { value: "color ",   label: "color — set color (name/#hex/0-255)" },
+        { value: "speed ",   label: "speed — set speed" },
+        { value: "off",      label: "off — restore default spinner" },
+        { value: "on",       label: "on — re-enable loader" },
+        { value: "reset",    label: "reset — defaults" },
+      ];
+      if (!prefix) return subs;
+
+      const parts = prefix.split(/\s+/);
+      if (parts.length >= 2) {
+        const sub = parts[0]!;
+        const arg = parts.slice(1).join(" ");
+        if (sub === "pattern") {
+          return PATTERN_KEYS.filter((k) => k.startsWith(arg)).map((k) => ({
+            value: `${sub} ${k}`,
+            label: `${k} — ${PATTERNS[k]!.name}`,
+          }));
+        }
+        if (sub === "color") {
+          return (COLORS as readonly string[])
+            .filter((c) => c.startsWith(arg))
+            .map((c) => ({ value: `${sub} ${c}`, label: c }));
+        }
+        return null;
+      }
+      const filtered = subs.filter((s) => s.value.startsWith(prefix));
+      return filtered.length > 0 ? filtered : null;
+    },
+    handler: async (args, ctx) => {
+      const parts = args.trim().split(/\s+/);
+      const sub = parts[0]?.toLowerCase();
+      const value = parts.slice(1).join(" ");
+
+      switch (sub) {
+        case "pattern": {
+          const key = value.toLowerCase();
+          if (!key || !PATTERNS[key]) {
+            ctx.ui.notify(
+              PATTERN_KEYS.map((k) => `  ${k} — ${PATTERNS[k]!.name}`).join("\n"),
+              "info",
+            );
+            return;
+          }
+          config.pattern = key;
+          saveConfig(config);
+          apply(ctx);
+          ctx.ui.notify(`Pattern → ${PATTERNS[key]!.name}`, "info");
+          return;
+        }
+        case "color": {
+          if (!value) {
+            ctx.ui.notify(
+              `/loader color <name|#hex|0-255>  (${config.color})\n` +
+              `Named: ${COLORS.join(", ")}\n` +
+              `Ex: accent, 196, #ff6600`,
+              "info",
+            );
+            return;
+          }
+          if ((COLORS as readonly string[]).includes(value)) {
+            config.color = value;
+            saveConfig(config);
+            apply(ctx);
+            return;
+          }
+          if (/^#[0-9a-fA-F]{6}$/.test(value)) {
+            config.color = value;
+            saveConfig(config);
+            apply(ctx);
+            return;
+          }
+          if (/^\d{1,3}$/.test(value)) {
+            const n = parseInt(value, 10);
+            if (n >= 0 && n <= 255) {
+              config.color = value;
+              saveConfig(config);
+              apply(ctx);
+              return;
+            }
+          }
+          ctx.ui.notify(
+            `/loader color <name|#hex|0-255>  (${config.color})\n` +
+            `Named: ${COLORS.join(", ")}\n` +
+            `Ex: accent, 196, #ff6600`,
+            "info",
+          );
+          return;
+        }
+        case "speed": {
+          const n = parseFloat(value);
+          if (isNaN(n) || n < 0.25 || n > 10.0) {
+            ctx.ui.notify(`/loader speed <0.25-10.0>  (${config.speed}x)`, "info");
+            return;
+          }
+          config.speed = n;
+          saveConfig(config);
+          apply(ctx);
+          return;
+        }
+        case "off": {
+          disabled = true;
+          ctx.ui.setWorkingIndicator();
+          ctx.ui.notify("Loader off", "info");
+          return;
+        }
+        case "on": {
+          disabled = false;
+          apply(ctx);
+          ctx.ui.notify("Loader on", "info");
+          return;
+        }
+        case "preview": {
+          const startIdx = value
+            ? Math.max(0, PATTERN_KEYS.indexOf(value.toLowerCase()))
+            : Math.max(0, PATTERN_KEYS.indexOf(config.pattern));
+          const previewColors = [...PREVIEW_COLORS];
+          if (!previewColors.includes(config.color)) previewColors.push(config.color);
+          ctx.ui.custom<string | null>(
+            (tui, theme, _kb, done) => new LoaderPreviewComponent(
+              tui, theme, done,
+              startIdx,
+              PATTERN_KEYS,
+              config.color,
+              previewColors,
+              config.speed,
+              (pattern, color, speed) => {
+                config.pattern = pattern;
+                config.color = color;
+                config.speed = speed;
+                saveConfig(config);
+                apply(ctx);
+                ctx.ui.notify(`Selected: ${PATTERNS[pattern]?.name ?? pattern} · ${color} · ${speed}x`, "info");
+              },
+            ),
+            { overlay: true },
+          );
+          return;
+        }
+        case "reset": {
+          config = { ...DEFAULTS };
+          saveConfig(config);
+          apply(ctx);
+          ctx.ui.notify("Reset → Default, accent, 1x", "info");
+          return;
+        }
+        default: {
+          const p = PATTERNS[config.pattern];
+          ctx.ui.notify(
+            `/loader [pattern|color|preview|speed|reset]\n` +
+              `${p?.name ?? config.pattern} · ${config.color} · ${config.speed}x`,
+            "info",
+          );
+        }
+      }
+    },
+  });
+}

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@graedenn/pi-loader",
+  "version": "1.0.0",
+  "description": "Braille-dot working indicator for pi coding agent — replaces the default spinner with 54+ configurable animations",
+  "keywords": ["pi-package", "pi", "coding-agent", "extension", "loader", "spinner", "braille", "dot-matrix"],
+  "license": "MIT",
+  "author": "Graeden",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/graedenn/pi-loader.git"
+  },
+  "bugs": {
+    "url": "https://github.com/graedenn/pi-loader/issues"
+  },
+  "homepage": "https://github.com/graedenn/pi-loader#readme",
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*"
+  },
+  "pi": {
+    "extensions": ["./index.ts"],
+    "video": "https://github.com/graedenn/pi-loader/raw/main/demo/pi-loader-demo.mp4"
+  }
+}

package/patterns.ts

@@ -0,0 +1,112 @@
+export const PATTERNS = {
+  "default": { type: "raw", name: "Default",
+    frames: ["⠋","⠙","⠹","⠸","⠼","⠴","⠦","⠧","⠇","⠏"], defaultSpeed: 1.0 },
+  "single-dots": { type: "raw", name: "Single Dots",
+    frames: ["⠁","⠂","⠄","⡀","⢀","⠠","⠐","⠈"], defaultSpeed: 1.0 },
+  "single-bounce": { type: "raw", name: "Single Bounce",
+    frames: ["⠁","⠂","⠄","⡀","⢀","⠠","⠐","⠈","⠐","⠠","⢀","⡀","⠄","⠂"], defaultSpeed: 1.0 },
+  "single-fill": { type: "raw", name: "Single Fill",
+    frames: ["⠁","⠃","⠇","⡇","⡏","⡟","⡿","⣿","⡿","⡟","⡏","⡇","⠇","⠃"], defaultSpeed: 1.0 },
+  "single-sweep": { type: "raw", name: "Single Sweep",
+    frames: ["⠁","⠉","⠘","⠰","⢠","⣀","⡄","⠆"], defaultSpeed: 1.0 },
+  "half-helix":   { type: "raw", name: "Half Helix",
+    frames: ["⣨⠿","⣬⠟","⣤⠟","⣴⠛","⣴⡛","⢶⣋","⢾⣉","⠾⣍","⠿⣅","⠻⣥","⠻⣦","⢛⣦","⢙⣶","⣙⡶","⣉⡷","⣩⠷"], defaultSpeed: 1.0 },
+  "helix-core":   { type: "raw", name: "Helix Core",
+    frames: ["⢠⡫","⡠⡻","⣔⠝","⢴⠋","⣮⠊","⡷⡁","⢕⡅","⢟⢄","⠫⣢","⠙⡦","⠑⣵","⢈⢾"], defaultSpeed: 1.0 },
+  "helix-glow":   { type: "raw", name: "Helix Glow",
+    frames: ["⠪⡱","⢣⢱","⢃⢕","⡑⢜","⡱⢸","⡡⢪","⡌⢪","⡜⡪","⡜⡱","⢔⠱","⢆⠕","⡎⡜","⡪⡘","⡣⢊","⡇⢎","⡕⢌","⡕⢡","⢕⢣","⢎⢣","⠎⡢"], defaultSpeed: 1.0 },
+  "thought-helix": { type: "raw", name: "Thought Helix",
+    frames: ["⢸⡇","⢰⡇","⡰⡃","⡸⢇","⢸⢇","⢜⢡","⢜⢣","⢜⡣","⠸⡢","⠪⡰","⢪⡕","⢘⡕","⢑⡕","⢑⡜","⢱⡎","⢨⡎","⢨⠎","⢸⡎","⢸⡇"], defaultSpeed: 1.0 },
+  "pulse-ladder": { type: "raw", name: "Pulse Ladder",
+    frames: ["⡀⢠","⡄⢀","⡆⠀","⠇⠀","⠋⠀","⠙⠀","⠸⠀","⢰⠀","⢠⡀","⢀⡄","⠀⡆","⠀⠇","⠀⠋","⠀⠙","⠀⠸","⠀⢰"], defaultSpeed: 1.3 },
+  "core-spiral":  { type: "raw", name: "Core Spiral",
+    frames: ["⠡⠄","⠩⠀","⠉⠁","⠈⠉","⠀⠙","⠀⠸","⠀⢰","⠀⣠","⢀⣀","⣀⡀","⣄⠀","⡆⠀","⠖⠀","⠒⠂","⠐⠆","⠠⠆"], defaultSpeed: 1.2 },
+  "twin-orbit":   { type: "raw", name: "Twin Orbit",
+    frames: ["⠷⠀","⠧⠄","⠫⠄","⠩⠅","⠨⠍","⠈⠏","⠀⠟","⠀⠾","⠀⢶","⠐⢲","⠐⣢","⢐⣂","⣐⡂","⣰⡀","⣴⠀","⡶⠀"], defaultSpeed: 1.0 },
+  "infinity-run": { type: "raw", name: "Infinity Run",
+    frames: ["⠐⠄","⠠⠀","⠀⢀","⡀⠠","⡀⠀","⠄⠐","⠀⠈","⠂⠈","⠁⠀","⠀⠂","⠐⠄","⠠⠀","⠀⢀","⡀⠠","⡀⠀","⠄⠐","⠀⠈","⠂⠈","⠁⠀","⠀⠂"], defaultSpeed: 1.0 },
+  "radar-arc":    { type: "raw", name: "Radar Arc",
+    frames: ["⠀⠰","⠀⠠","⠀⠤","⠀⡄","⠀⡀","⢀⡀","⢀⠀","⢠⠀","⠤⠀","⠄⠀","⠆⠀","⠂⠀","⠒⠀","⠘⠀","⠈⠀","⠈⠁","⠀⠁","⠀⠃","⠀⠒","⠀⠐"], defaultSpeed: 1.5 },
+  "scan":        { type: "raw", name: "Scan",
+    frames: ["⡇⠀","⣿⠀","⢸⡇","⠀⣿","⠀⢸","⠀⠀"], defaultSpeed: 1.0 },
+  "sweep":       { type: "raw", name: "Sweep",
+    frames: ["⡀⠀","⣀⠀","⣄⠀","⣆⠀","⣇⠀","⣿⠀","⢸⡇","⠀⣿","⠀⢸","⠀⢰","⠀⢠","⠀⣀","⠀⡀"], defaultSpeed: 1.0 },
+  "agent-sweep": { type: "raw", name: "Agent Sweep",
+    frames: ["⠁⠀","⠃⠀","⠇⠀","⡇⠀","⣿⠀","⢸⡇","⠀⣿","⠀⢸","⠀⠸","⠀⠘","⠀⠈","⠀⠐","⠀⠠","⠀⢀","⠀⡀","⢀⡀","⡀⠀","⠄⠀","⠂⠀"], defaultSpeed: 1.0 },
+  "sound-bars":   { type: "raw", name: "Sound Bars",
+    frames: ["⣰⣦","⣴⣤","⣶⣦","⣶⣄","⣶⣤","⣶⣰","⣦⣴","⣆⣶","⣦⣦","⣰⣦","⣴⣦","⣶⣆","⣶⣦","⣶⣴","⣦⣶","⣤⣶","⣰⣶"], defaultSpeed: 1.0 },
+  "perimeter-spin-light": { type: "raw", name: "Perimeter Spin Light",
+    frames: ["⠃⠀","⠉⠀","⠈⠁","⠀⠉","⠀⠘","⠀⠰","⠀⢠","⠀⣀","⢀⡀","⣀⠀","⡄⠀","⠆⠀"], defaultSpeed: 1.0 },
+  "perimeter-spin": { type: "raw", name: "Perimeter Spin",
+    frames: ["⠇⠀","⠋⠀","⠉⠁","⠈⠉","⠀⠙","⠀⠸","⠀⢰","⠀⣠","⢀⣀","⣀⡀","⣄⠀","⡆⠀"], defaultSpeed: 1.0 },
+  "perimeter-spin-bold": { type: "raw", name: "Perimeter Spin Bold",
+    frames: ["⡇⠀","⠏⠀","⠋⠁","⠉⠉","⠈⠙","⠀⠹","⠀⢸","⠀⣰","⢀⣠","⣀⣀","⣄⡀","⣆⠀"], defaultSpeed: 0.95 },
+  "shuffle": { type: "raw", name: "Shuffle",
+    frames: ["⢄","⢂","⢁","⡁","⡈","⡐","⡠"], defaultSpeed: 1.0 },
+  "hangtime": { type: "raw", name: "Hangtime",
+    frames: ["⢀⠀","⡀⠀","⠄⠀","⢂⠀","⡂⠀","⠅⠀","⢃⠀","⡃⠀","⠍⠀","⢋⠀","⡋⠀","⠍⠁","⢋⠁","⡋⠁","⠍⠉","⠋⠉","⠋⠉","⠉⠙","⠉⠙","⠉⠩","⠈⢙","⠈⡙","⢈⠩","⡀⢙","⠄⡙","⢂⠩","⡂⢘","⠅⡘","⢃⠨","⡃⢐","⠍⡐","⢋⠠","⡋⢀","⠍⡁","⢋⠁","⡋⠁","⠍⠉","⠋⠉","⠋⠉","⠉⠙","⠉⠙","⠉⠩","⠈⢙","⠈⡙","⠈⠩","⠀⢙","⠀⡙","⠀⠩","⠀⢘","⠀⡘","⠀⠨","⠀⢐","⠀⡐","⠀⠠","⠀⢀","⠀⡀"], defaultSpeed: 1.0 },
+  "line-spin": { type: "raw", name: "Line Spin",
+    frames: ["⠶⠶","⠒⠤","⠑⢄","⠘⡄","⢸⡇","⢠⠃","⡠⠊","⠤⠒"], defaultSpeed: 1.0 },
+  "ray-spin": { type: "raw", name: "Ray Spin",
+    frames: ["⠀⠶","⠀⢄","⢠⡄","⡠⠀","⠶⠀","⠑⠀","⠘⠃","⠀⠊"], defaultSpeed: 1.0 },
+  "rotating-x":   { type: "raw", name: "Rotating X",
+    frames: ["⠕⠪","⠚⡤","⠕⠪","⢤⠓"], defaultSpeed: 1.0 },
+  "texture-flip":{ type: "raw", name: "Texture Flip",
+    frames: ["⡪⡪","⢕⢕"], defaultSpeed: 1.0 },
+  "neural-flicker": { type: "raw", name: "Neural Flicker",
+    frames: ["⠁⠈","⠂⠐","⠄⠠","⡀⢀","⢄⡠","⢆⡰","⢇⣰","⣿⣿","⣰⢇","⡰⢆","⡠⢄","⢀⡀","⠠⠄","⠐⠂","⠈⠁"], defaultSpeed: 1.0 },
+  "neural-flicker-chaos": { type: "raw", name: "Neural Flicker Chaos",
+    frames: ["⠁⠈","⠂⠐","⠄⠠","⡀⢀","⢄⡠","⢆⡰","⢇⣰","⣿⣿","⣰⢇","⡰⢆","⡠⢄","⢀⡀","⠠⠄","⠐⠂","⠈⠁","⠈⠂","⠘⠄","⠸⡀","⢸⢀","⣸⠠","⣰⠐","⢠⠈","⡀⠘","⠄⠸","⠂⢸","⠁⣸","⠀⠰","⠈⠠","⠐⠄","⠂⠁","⠆⠈","⡆⠐","⣆⠠","⣇⢀","⢇⡀","⠇⡠","⠃⡰","⠁⣰","⠈⢠","⠐⡀","⠠⠄"], defaultSpeed: 1.0 },
+  "neural-flicker-drift": { type: "raw", name: "Neural Flicker Drift",
+    frames: ["⠁⠈","⠂⠐","⠄⠠","⡀⢀","⢄⡠","⢆⡰","⢇⣰","⣇⣸","⣰⢇","⡰⢆","⡠⢄","⢀⡀","⠠⠄","⠐⠂","⠈⠁","⠁⠂","⠃⠄","⠇⡀","⡇⢀","⣇⠠","⢇⠐","⠇⠈","⠃⠘","⠁⠸","⠂⢸","⠄⣸","⡀⢰","⢀⠠","⠠⠐","⠈⠄","⠘⡀","⠸⢀","⢸⠠","⣸⠐","⢰⠈","⠠⠘","⠐⠸","⠈⢸","⠐⣸","⠠⢰","⢀⠠"], defaultSpeed: 1.0 },
+  "neural-flicker-thought": { type: "raw", name: "Neural Flicker Thought",
+    frames: ["⠁⠈","⠂⠐","⠄⠠","⡀⢀","⢄⡠","⢆⡰","⢇⣰","⣇⣸","⢇⣰","⡰⢆","⡠⢄","⢀⡀","⠠⠄","⠐⠂","⠈⠁","⠈⠁","⠘⠂","⠸⠄","⢸⡀","⣸⢀","⢰⠠","⠠⠐","⠐⠈","⠘⠁","⠸⠂","⢸⠄","⣸⡀","⢰⢀","⠠⠠","⠂⠈","⠆⠐","⡆⠠","⣆⢀","⢆⡀","⠆⡠","⠂⡰","⠁⣰","⠈⢠","⠐⡀","⠠⠄","⢀⠂"], defaultSpeed: 1.0 },
+  "neural-scatter": { type: "raw", name: "Neural Scatter",
+    frames: ["⠁⠈","⠂⡐","⡄⠠","⠐⢀","⢄⠂","⠆⡰","⢇⠐","⠃⣰","⡠⠄","⠘⢆","⢀⡁","⠰⠂","⡂⠈","⠄⢠","⠈⡐","⠂⠠"], defaultSpeed: 1.15 },
+  "neural-spike": { type: "raw", name: "Neural Spike",
+    frames: ["⠁⠈","⠃⠐","⡂⠠","⠄⢀","⢄⠁","⠆⡠","⢂⠘","⠁⣰","⡀⠆","⠘⢄","⠠⡂","⠂⢀","⡁⠐","⠄⠈"], defaultSpeed: 1.2 },
+  "neural-random-walk": { type: "raw", name: "Neural Random Walk",
+    frames: ["⠁⠈","⠂⠐","⡄⠠","⢀⠂","⠆⡀","⠐⢄","⢂⠘","⠁⡰","⡠⠄","⠘⢂","⠄⡐","⠂⢀","⡁⠠","⠈⠆","⠐⡀","⢄⠁"], defaultSpeed: 1.1 },
+  "neural-cross-spark": { type: "raw", name: "Neural Cross Spark",
+    frames: ["⠁⠈","⠂⠐","⠄⠠","⡀⢀","⢄⡠","⠆⡰","⢂⡐","⠁⣰","⡠⠄","⠘⢆","⠐⢂","⠈⡁","⠠⠄","⠂⠐"], defaultSpeed: 1.0 },
+  "neural-offset": { type: "raw", name: "Neural Offset",
+    frames: ["⠁⠈","⡂⠐","⠄⢠","⢀⠂","⠆⡀","⠐⢄","⢂⠘","⠁⢰","⡠⠄","⠘⢂","⠄⡐","⠂⢀","⡁⠠","⠈⠆"], defaultSpeed: 1.15 },
+  "neural-braid": { type: "raw", name: "Neural Braid",
+    frames: ["⢨⠎","⢨⡎","⢠⡇","⢰⡃","⡰⡇","⡸⢅","⡜⢅","⡜⢇","⢜⢢","⢎⢢","⢎⢣","⢪⢱","⠣⡱","⠱⡸","⠑⡜","⢑⡜","⢘⡜","⢈⡎"], defaultSpeed: 1.0 },
+  "thinking-pulse": { type: "raw", name: "Thinking Pulse",
+    frames: ["⠁⠀","⠃⠀","⠇⠀","⡇⠀","⣇⠀","⣿⠀","⢸⡇","⠀⣿","⠀⣸","⠀⢸","⠀⠸","⠀⠘","⠀⠈","⠀⠐","⠀⠠","⠀⢀","⠀⡀","⢀⡀","⡀⠀","⠄⠀","⠂⠀"], defaultSpeed: 1.0 },
+  "soft-thinking": { type: "raw", name: "Soft Thinking",
+    frames: ["⠁⠀","⠂⠀","⠄⠀","⡀⠀","⢀⠀","⠀⢀","⠀⠠","⠀⠐","⠀⠈","⠀⠐","⠀⠠","⠀⢀","⢀⠀","⡀⠀","⠄⠀","⠂⠀"], defaultSpeed: 1.0 },
+  "deep-thought": { type: "raw", name: "Deep Thought",
+    frames: ["⠁⠀","⠃⠀","⠇⠀","⡇⠀","⣇⠀","⣧⠀","⣿⠀","⣿⡇","⢸⣿","⠀⣿","⠀⣼","⠀⣸","⠀⢰","⠀⠠","⠀⠐","⠀⠈","⠀⠐","⠀⠠","⠀⢀","⠀⡀","⢀⡀","⡀⠀","⠄⠀","⠂⠀"], defaultSpeed: 1.0 },
+  "signal-search": { type: "raw", name: "Signal Search",
+    frames: ["⠁⠀","⠃⠀","⠇⠀","⡇⠀","⡇⠁","⡇⠃","⡇⠇","⡇⡇","⠇⡇","⠃⡇","⠁⡇","⠀⡇","⠀⠇","⠀⠃","⠀⠁"], defaultSpeed: 1.0 },
+  "binary-thought": { type: "raw", name: "Binary Thought",
+    frames: ["⠁⠈","⠃⠘","⠇⠸","⡇⢸","⣇⣸","⡇⢸","⠇⠸","⠃⠘","⠁⠈","⠂⠐","⠆⠰","⠄⠠","⠂⠐"], defaultSpeed: 1.0 },
+  "center-spark": { type: "raw", name: "Center Spark",
+    frames: ["⠲⣆","⠲⢦","⠳⠦","⠹⠦","⠹⠶","⠸⠗","⡸⠟","⡰⠏","⣰⠎","⣴⡎","⢴⡆","⠶⣆"], defaultSpeed: 1.0 },
+  "synapse-wave": { type: "raw", name: "Synapse Wave",
+    frames: ["⣀⠝","⢄⠕","⢐⠕","⣠⠋","⡤⠊","⡢⠊","⢨⡊","⢴⠁","⢖⠁","⢕⢁","⠪⡄","⠺⡀","⠫⣀","⠑⢤","⠑⢔","⢑⢅","⠈⡦","⠈⡲","⡈⡪","⢨⠔"], defaultSpeed: 1.0 },
+  "inner-current": { type: "raw", name: "Inner Current",
+    frames: ["⢰⠇","⢰⠃","⢠⠃","⢠⠇","⠸⡇","⠸⡅","⠸⡁","⢸⡄","⢸⡅","⢸⡇","⢈⠇","⢈⡇","⢈⡆"], defaultSpeed: 1.0 },
+  "bouncing-block": { type: "raw", name: "Bouncing Block",
+    frames: ["⡇⠀","⣇⠀","⣿⠀","⢸⡇","⠀⣿","⠀⣸","⠀⢸","⠀⣸","⠀⣿","⢸⡇","⣿⠀","⣇⠀"], defaultSpeed: 1.0 },
+  "face":         { type: "raw", name: "Smiley Face",
+    frames: ["⣀⣀","⣁⣈","⢅⡨","⢄⡨","⢅⡨","⣁⣈"], defaultSpeed: 1.0 },
+  "snake-crawl": { type: "raw", name: "Snake Crawl",
+    frames: ["⠉⠉","⠉⠁","⠉⠁","⠉⠉","⠈⠙","⠀⠛","⠐⠚","⠒⠒","⠖⠂","⠶⠀","⠦⠄","⠤⠤","⠠⢤","⠀⣤","⢀⣠","⣀⣀","⣀⡀","⣀⡀","⣀⣀","⢀⣠","⠀⣤","⠠⢤","⠤⠤","⠦⠄","⠶⠀","⠖⠂","⠒⠒","⠐⠚","⠀⠛","⠈⠙"], defaultSpeed: 1.0 },
+  "snake-loop": { type: "raw", name: "Snake Loop",
+    frames: ["⠉⠉","⠈⠙","⠀⠛","⠐⠚","⠒⠒","⠖⠂","⠶⠀","⠦⠄","⠤⠤","⠠⢤","⠀⣤","⢀⣠","⣀⣀","⣄⡀","⣤⠀","⡤⠄","⠤⠤","⠠⠴","⠀⠶","⠐⠲","⠒⠒","⠓⠂","⠛⠀","⠋⠁"], defaultSpeed: 1.0 },
+  "circle": { type: "raw", name: "Circle",
+    frames: [" ",".","o","O","@",""], defaultSpeed: 1.0 },
+  "square": { type: "raw", name: "Square",
+    frames: ["□","■"], defaultSpeed: 1.0 },
+  "twinkle": { type: "raw", name: "Twinkle",
+    frames: ["+","×"], defaultSpeed: 1.0 },
+  "corners": { type: "raw", name: "Corners",
+    frames: ["◢","◣","◤","◥"], defaultSpeed: 1.0 },
+  "growth": { type: "raw", name: "Growth",
+    frames: ["▁","▃","▄","▅","▆","▇","▆","▅","▄","▃"], defaultSpeed: 1.0 },
+};
+
+export const PATTERN_KEYS = Object.keys(PATTERNS);