@pi-archimedes/core 1.5.0 → 1.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-archimedes/core",
-  "version": "1.5.0",
+  "version": "1.7.0",
   "type": "module",
   "keywords": [
     "pi-package"

package/src/bus.test.ts

@@ -0,0 +1,154 @@
+import { describe, it, expect, afterEach } from "vitest";
+import { getBus, initBus, Events } from "./bus.js";
+
+// ── globalThis cleanup ──────────────────────────────────────────────────────
+
+const BUS_KEY = Symbol.for("archimedes:bus");
+const QUEUE_KEY = Symbol.for("archimedes:busQueue");
+
+afterEach(() => {
+  // Reset globalThis bus and queue to avoid test pollution
+  delete (globalThis as Record<symbol, unknown>)[BUS_KEY];
+  delete (globalThis as Record<symbol, unknown>)[QUEUE_KEY];
+});
+
+// ── emit → on delivery ─────────────────────────────────────────────────────
+
+describe("emit → on delivery", () => {
+  it("subscriber receives payload", () => {
+    const bus = getBus();
+    const received: unknown[] = [];
+    bus.on("test:event", (payload) => received.push(payload));
+    bus.emit("test:event", { hello: "world" });
+    expect(received).toEqual([{ hello: "world" }]);
+  });
+});
+
+// ── multiple subscribers ────────────────────────────────────────────────────
+
+describe("multiple subscribers", () => {
+  it("all receive the event", () => {
+    const bus = getBus();
+    const a: unknown[] = [];
+    const b: unknown[] = [];
+    bus.on("multi", (p) => a.push(p));
+    bus.on("multi", (p) => b.push(p));
+    bus.emit("multi", "shared");
+    expect(a).toEqual(["shared"]);
+    expect(b).toEqual(["shared"]);
+  });
+});
+
+// ── unsubscribe ─────────────────────────────────────────────────────────────
+
+describe("unsubscribe", () => {
+  it("removed subscriber does not receive subsequent events", () => {
+    const bus = getBus();
+    const received: unknown[] = [];
+    const unsub = bus.on("unsub:test", (p) => received.push(p));
+    bus.emit("unsub:test", "first");
+    unsub();
+    bus.emit("unsub:test", "second");
+    expect(received).toEqual(["first"]);
+  });
+});
+
+// ── error isolation ─────────────────────────────────────────────────────────
+
+describe("error isolation", () => {
+  it("one listener throwing does not prevent others from receiving", () => {
+    const bus = getBus();
+    const received: unknown[] = [];
+    bus.on("err:test", () => {
+      throw new Error("boom");
+    });
+    bus.on("err:test", (p) => received.push(p));
+    bus.emit("err:test", "payload");
+    expect(received).toEqual(["payload"]);
+  });
+});
+
+// ── late subscriber queue ───────────────────────────────────────────────────
+
+describe("late subscriber queue", () => {
+  it("events emitted before on() are delivered when subscriber registers", () => {
+    // Create a fresh bus
+    const bus = getBus();
+
+    // Emit before anyone subscribes — this queues the event
+    bus.emit("queued:event", "queued-payload");
+
+    // Now subscribe — queued events should be delivered
+    const received: unknown[] = [];
+    bus.on("queued:event", (p) => received.push(p));
+
+    expect(received).toEqual(["queued-payload"]);
+  });
+});
+
+// ── initBus ─────────────────────────────────────────────────────────────────
+
+describe("initBus", () => {
+  it("flushes queued events to subscribers that registered before init", () => {
+    // Emit before any subscriber exists — queues the event
+    const bus = getBus();
+    bus.emit("init:test", "queued-value");
+
+    // Subscribe — on() drains queue and delivers
+    const received: unknown[] = [];
+    bus.on("init:test", (p) => received.push(p));
+    expect(received).toEqual(["queued-value"]);
+  });
+
+  it("initBus re-emits queued events through the bus", () => {
+    // Emit with no subscriber — queues
+    const bus = getBus();
+    bus.emit("init:test2", "queued");
+
+    // initBus re-emits through the bus
+    initBus();
+
+    // Since no subscriber for test2, re-emit goes back to queue.
+    // Now subscribe — on() drains the re-queued event
+    const received: unknown[] = [];
+    bus.on("init:test2", (p) => received.push(p));
+    expect(received).toEqual(["queued"]);
+  });
+
+  it("initBus snapshots and clears queue before iterating", () => {
+    // Emit with no subscriber — queues
+    const bus = getBus();
+    bus.emit("snapshot:test", "a");
+    bus.emit("snapshot:test", "b");
+
+    // Subscribe — on() drains queue and delivers (but queue array persists)
+    const received: unknown[] = [];
+    bus.on("snapshot:test", (p) => received.push(p));
+    expect(received).toEqual(["a", "b"]);
+
+    // Queue array still has items (on() delivers but doesn't remove)
+    const queueBefore = (globalThis as Record<symbol, unknown>)[QUEUE_KEY] as Array<unknown>;
+    expect(queueBefore.length).toBe(2);
+
+    // initBus snapshots, clears queue, and re-emits
+    initBus();
+    // Re-emits go to existing subscriber (not re-queued)
+    expect(received).toEqual(["a", "b", "a", "b"]);
+
+    // Queue is now empty (initBus cleared it)
+    const queueAfter = (globalThis as Record<symbol, unknown>)[QUEUE_KEY] as Array<unknown>;
+    expect(queueAfter.length).toBe(0);
+  });
+});
+
+// ── Events constant ─────────────────────────────────────────────────────────
+
+describe("Events constant", () => {
+  it("all event names are defined", () => {
+    expect(Events.COST_UPDATE).toBe("archimedes:cost_update");
+    expect(Events.TODOS_UPDATE).toBe("archimedes:todos_update");
+    expect(Events.TODOS_CLEAR).toBe("archimedes:todos_clear");
+    expect(Events.ASK_REQUEST).toBe("archimedes:ask_request");
+    expect(Events.ASK_RESPONSE).toBe("archimedes:ask_response");
+  });
+});

package/src/color.test.ts

@@ -0,0 +1,331 @@
+import { describe, it, expect } from "vitest";
+import {
+  hexToRgb,
+  rgbToHex,
+  rgbToHsl,
+  hslToRgb,
+  ansi256ToRgb,
+  parseAnsiFgToRgb,
+  deriveDimColor,
+  rgbToTruecolorFg,
+  gray,
+  rgb,
+  extractRgb,
+  lerp,
+} from "./color.js";
+
+// ── hexToRgb ────────────────────────────────────────────────────────────────
+
+describe("hexToRgb", () => {
+  it("parses valid 6-char hex", () => {
+    expect(hexToRgb("#ff00aa")).toEqual({ r: 255, g: 0, b: 170 });
+  });
+
+  it("parses 3-char shorthand", () => {
+    expect(hexToRgb("#f0a")).toEqual({ r: 255, g: 0, b: 170 });
+  });
+
+  it("parses without hash prefix", () => {
+    expect(hexToRgb("ff00aa")).toEqual({ r: 255, g: 0, b: 170 });
+  });
+
+  it("parses with hash prefix", () => {
+    expect(hexToRgb("#ff00aa")).toEqual({ r: 255, g: 0, b: 170 });
+  });
+
+  it("handles mixed case", () => {
+    expect(hexToRgb("#Ff00Aa")).toEqual({ r: 255, g: 0, b: 170 });
+  });
+
+  it("throws on invalid input", () => {
+    expect(() => hexToRgb("#gggggg")).toThrow("Invalid hex color");
+    expect(() => hexToRgb("#ff")).toThrow("Invalid hex color");
+    expect(() => hexToRgb("#ffffffg")).toThrow("Invalid hex color");
+    expect(() => hexToRgb("")).toThrow("Invalid hex color");
+  });
+});
+
+// ── rgbToHex ────────────────────────────────────────────────────────────────
+
+describe("rgbToHex", () => {
+  it("round-trips with hexToRgb", () => {
+    const hex = "#ff00aa";
+    expect(rgbToHex(hexToRgb(hex))).toBe(hex.toLowerCase());
+  });
+
+  it("round-trips shorthand hex", () => {
+    const hex = "#f0a";
+    // Shorthand expands to 6-char, so round-trip is 6-char form
+    expect(rgbToHex(hexToRgb(hex))).toBe("#ff00aa");
+  });
+
+  it("clamps values to 0-255", () => {
+    expect(rgbToHex({ r: -10, g: 0, b: 0 })).toBe("#000000");
+    expect(rgbToHex({ r: 255, g: 300, b: 0 })).toBe("#ffff00");
+    expect(rgbToHex({ r: 255, g: 255, b: 255 })).toBe("#ffffff");
+  });
+
+  it("pads single-digit hex values", () => {
+    expect(rgbToHex({ r: 0, g: 0, b: 10 })).toBe("#00000a");
+  });
+});
+
+// ── rgbToHsl ────────────────────────────────────────────────────────────────
+
+describe("rgbToHsl", () => {
+  it("grayscale r=g=b returns s=0", () => {
+    const hsl = rgbToHsl({ r: 128, g: 128, b: 128 });
+    expect(hsl.s).toBe(0);
+    expect(hsl.h).toBe(0);
+    expect(hsl.l).toBeCloseTo(128 / 255);
+  });
+
+  it("pure red", () => {
+    const hsl = rgbToHsl({ r: 255, g: 0, b: 0 });
+    expect(hsl.h).toBe(0);
+    expect(hsl.s).toBe(1);
+    expect(hsl.l).toBe(0.5);
+  });
+
+  it("pure green", () => {
+    const hsl = rgbToHsl({ r: 0, g: 255, b: 0 });
+    expect(hsl.h).toBe(120);
+    expect(hsl.s).toBe(1);
+    expect(hsl.l).toBe(0.5);
+  });
+
+  it("pure blue", () => {
+    const hsl = rgbToHsl({ r: 0, g: 0, b: 255 });
+    expect(hsl.h).toBe(240);
+    expect(hsl.s).toBe(1);
+    expect(hsl.l).toBe(0.5);
+  });
+
+  it("white returns h=0, s=0, l=1", () => {
+    const hsl = rgbToHsl({ r: 255, g: 255, b: 255 });
+    expect(hsl.h).toBe(0);
+    expect(hsl.s).toBe(0);
+    expect(hsl.l).toBe(1);
+  });
+
+  it("black returns h=0, s=0, l=0", () => {
+    const hsl = rgbToHsl({ r: 0, g: 0, b: 0 });
+    expect(hsl.h).toBe(0);
+    expect(hsl.s).toBe(0);
+    expect(hsl.l).toBe(0);
+  });
+});
+
+// ── hslToRgb ────────────────────────────────────────────────────────────────
+
+describe("hslToRgb", () => {
+  it("round-trips with rgbToHsl for pure red", () => {
+    const hsl = rgbToHsl({ r: 255, g: 0, b: 0 });
+    expect(hslToRgb(hsl)).toEqual({ r: 255, g: 0, b: 0 });
+  });
+
+  it("round-trips with rgbToHsl for pure green", () => {
+    const hsl = rgbToHsl({ r: 0, g: 255, b: 0 });
+    expect(hslToRgb(hsl)).toEqual({ r: 0, g: 255, b: 0 });
+  });
+
+  it("round-trips with rgbToHsl for pure blue", () => {
+    const hsl = rgbToHsl({ r: 0, g: 0, b: 255 });
+    expect(hslToRgb(hsl)).toEqual({ r: 0, g: 0, b: 255 });
+  });
+
+  it("s=0 produces grayscale", () => {
+    const result = hslToRgb({ h: 0, s: 0, l: 0.5 });
+    expect(result.r).toBe(result.g);
+    expect(result.g).toBe(result.b);
+  });
+
+  it("h wraps at 360", () => {
+    const a = hslToRgb({ h: 0, s: 1, l: 0.5 });
+    const b = hslToRgb({ h: 360, s: 1, l: 0.5 });
+    expect(a).toEqual(b);
+  });
+
+  it("negative h wraps correctly", () => {
+    const a = hslToRgb({ h: 0, s: 1, l: 0.5 });
+    const b = hslToRgb({ h: -360, s: 1, l: 0.5 });
+    expect(a).toEqual(b);
+  });
+});
+
+// ── ansi256ToRgb ────────────────────────────────────────────────────────────
+
+describe("ansi256ToRgb", () => {
+  it("code 0 returns black", () => {
+    expect(ansi256ToRgb(0)).toEqual({ r: 0, g: 0, b: 0 });
+  });
+
+  it("code 9 returns red", () => {
+    expect(ansi256ToRgb(9)).toEqual({ r: 255, g: 0, b: 0 });
+  });
+
+  it("code 15 returns white", () => {
+    expect(ansi256ToRgb(15)).toEqual({ r: 255, g: 255, b: 255 });
+  });
+
+  it("code 16 returns cube start (0,0,0)", () => {
+    expect(ansi256ToRgb(16)).toEqual({ r: 0, g: 0, b: 0 });
+  });
+
+  it("code 196 returns cube red (255,0,0)", () => {
+    expect(ansi256ToRgb(196)).toEqual({ r: 255, g: 0, b: 0 });
+  });
+
+  it("code 231 returns cube end (255,255,255)", () => {
+    expect(ansi256ToRgb(231)).toEqual({ r: 255, g: 255, b: 255 });
+  });
+
+  it("code 232 returns grayscale start (8,8,8)", () => {
+    expect(ansi256ToRgb(232)).toEqual({ r: 8, g: 8, b: 8 });
+  });
+
+  it("code 255 returns grayscale end (238,238,238)", () => {
+    expect(ansi256ToRgb(255)).toEqual({ r: 238, g: 238, b: 238 });
+  });
+
+  it("out-of-range throws", () => {
+    expect(() => ansi256ToRgb(-1)).toThrow("out of range");
+    expect(() => ansi256ToRgb(256)).toThrow("out of range");
+  });
+});
+
+// ── parseAnsiFgToRgb ────────────────────────────────────────────────────────
+
+describe("parseAnsiFgToRgb", () => {
+  it("parses truecolor sequence", () => {
+    const result = parseAnsiFgToRgb("\x1b[38;2;255;128;64m");
+    expect(result).toEqual({ r: 255, g: 128, b: 64 });
+  });
+
+  it("parses 256 palette sequence", () => {
+    const result = parseAnsiFgToRgb("\x1b[38;5;196m");
+    expect(result).toEqual({ r: 255, g: 0, b: 0 });
+  });
+
+  it("returns null for empty input", () => {
+    expect(parseAnsiFgToRgb("")).toBeNull();
+  });
+
+  it("returns null for null input", () => {
+    expect(parseAnsiFgToRgb(null as unknown as string)).toBeNull();
+  });
+
+  it("returns null for non-matching string", () => {
+    expect(parseAnsiFgToRgb("hello")).toBeNull();
+  });
+});
+
+// ── deriveDimColor ──────────────────────────────────────────────────────────
+
+describe("deriveDimColor", () => {
+  it("number input with anchorLightness", () => {
+    const result = deriveDimColor(100, 0.5);
+    expect(typeof result).toBe("string");
+    expect(result.startsWith("#")).toBe(true);
+  });
+
+  it("string hex input with custom saturationFactor", () => {
+    const result = deriveDimColor("#ff0000", 0.3, 0.7);
+    expect(typeof result).toBe("string");
+    expect(result.startsWith("#")).toBe(true);
+  });
+
+  it("default saturationFactor is 0.5", () => {
+    const withDefault = deriveDimColor("#ff0000", 0.5);
+    const explicit = deriveDimColor("#ff0000", 0.5, 0.5);
+    expect(withDefault).toBe(explicit);
+  });
+
+  it("lightness clamping — anchorLightness limits l", () => {
+    // Pure red has l=0.5, anchorLightness=0.2 should clamp to 0.2
+    const result = deriveDimColor("#ff0000", 0.2);
+    const hsl = rgbToHsl(hexToRgb(result));
+    expect(hsl.l).toBeLessThanOrEqual(0.2);
+  });
+});
+
+// ── rgbToTruecolorFg ────────────────────────────────────────────────────────
+
+describe("rgbToTruecolorFg", () => {
+  it("produces correct format", () => {
+    expect(rgbToTruecolorFg({ r: 255, g: 128, b: 64 })).toBe(
+      "\x1b[38;2;255;128;64m"
+    );
+  });
+
+  it("clamps values to 0-255", () => {
+    expect(rgbToTruecolorFg({ r: -1, g: 0, b: 300 })).toBe(
+      "\x1b[38;2;0;0;255m"
+    );
+  });
+});
+
+// ── gray ────────────────────────────────────────────────────────────────────
+
+describe("gray", () => {
+  it("produces truecolor gray with correct level", () => {
+    expect(gray(128, "hello")).toBe("\x1b[38;2;128;128;128mhello\x1b[0m");
+  });
+
+  it("clamps level to 0-255", () => {
+    expect(gray(-10, "x")).toBe("\x1b[38;2;0;0;0mx\x1b[0m");
+    expect(gray(300, "x")).toBe("\x1b[38;2;255;255;255mx\x1b[0m");
+  });
+});
+
+// ── rgb ─────────────────────────────────────────────────────────────────────
+
+describe("rgb", () => {
+  it("produces truecolor with correct values", () => {
+    expect(rgb(255, 128, 64, "text")).toBe(
+      "\x1b[38;2;255;128;64mtext\x1b[0m"
+    );
+  });
+
+  it("floors float values", () => {
+    expect(rgb(255.9, 128.1, 64.5, "x")).toBe(
+      "\x1b[38;2;255;128;64mx\x1b[0m"
+    );
+  });
+});
+
+// ── extractRgb ──────────────────────────────────────────────────────────────
+
+describe("extractRgb", () => {
+  it("extracts from themed string", () => {
+    expect(extractRgb("\x1b[38;2;200;100;50mhello")).toEqual([200, 100, 50]);
+  });
+
+  it("returns default for non-themed string", () => {
+    expect(extractRgb("plain text")).toEqual([100, 100, 100]);
+  });
+
+  it("returns default for empty string", () => {
+    expect(extractRgb("")).toEqual([100, 100, 100]);
+  });
+});
+
+// ── lerp ────────────────────────────────────────────────────────────────────
+
+describe("lerp", () => {
+  it("t=0 returns a", () => {
+    expect(lerp(10, 20, 0)).toBe(10);
+  });
+
+  it("t=1 returns b", () => {
+    expect(lerp(10, 20, 1)).toBe(20);
+  });
+
+  it("t=0.5 returns midpoint", () => {
+    expect(lerp(10, 20, 0.5)).toBe(15);
+  });
+
+  it("works with negative values", () => {
+    expect(lerp(-10, 10, 0.5)).toBe(0);
+  });
+});

package/src/text.test.ts

@@ -0,0 +1,116 @@
+import { describe, it, expect } from "vitest";
+import { stripAnsi, isParentBorder, formatKey } from "./text.js";
+
+// ── stripAnsi ───────────────────────────────────────────────────────────────
+
+describe("stripAnsi", () => {
+  it("strips CSI sequences", () => {
+    expect(stripAnsi("\x1b[31mhello\x1b[0m")).toBe("hello");
+  });
+
+  it("strips multiple CSI sequences", () => {
+    expect(stripAnsi("\x1b[1;32mred\x1b[0m \x1b[33myellow\x1b[0m")).toBe(
+      "red yellow"
+    );
+  });
+
+  it("strips OSC sequences", () => {
+    expect(stripAnsi("before\x1b]0;title\x07after")).toBe("beforeafter");
+  });
+
+  it("strips OSC with ST (ESC \\)", () => {
+    expect(stripAnsi("before\x1b]0;title\x1b\\after")).toBe("beforeafter");
+  });
+
+  it("strips DCS sequences", () => {
+    expect(stripAnsi("before\x1bPdata\x07after")).toBe("beforeafter");
+  });
+
+  it("strips SOS sequences", () => {
+    expect(stripAnsi("before\x1b^data\x07after")).toBe("beforeafter");
+  });
+
+  it("strips APC sequences", () => {
+    expect(stripAnsi("before\x1b_data\x07after")).toBe("beforeafter");
+  });
+
+  it("strips PM sequences", () => {
+    expect(stripAnsi("before\x1b\\data\x07after")).toBe("beforeafter");
+  });
+
+  it("strips character set escapes (ESC ( / ESC ))", () => {
+    // The regex strips ESC( and ESC) but not the following charset designator
+    expect(stripAnsi("before\x1b(Bafter")).toBe("beforeBafter");
+    expect(stripAnsi("before\x1b)Bafter")).toBe("beforeBafter");
+  });
+
+  it("handles nested escapes", () => {
+    expect(stripAnsi("\x1b[1m\x1b[31mhello\x1b[0m\x1b[0m")).toBe("hello");
+  });
+
+  it("returns empty string for empty input", () => {
+    expect(stripAnsi("")).toBe("");
+  });
+
+  it("returns input unchanged for no-escape string", () => {
+    expect(stripAnsi("plain text")).toBe("plain text");
+  });
+
+  it("trims leading and trailing whitespace", () => {
+    expect(stripAnsi("  \x1b[31mhello\x1b[0m  ")).toBe("hello");
+  });
+});
+
+// ── isParentBorder ──────────────────────────────────────────────────────────
+
+describe("isParentBorder", () => {
+  it("returns true for border char", () => {
+    expect(isParentBorder("─")).toBe(true);
+  });
+
+  it("returns true for border with SGR", () => {
+    expect(isParentBorder("\x1b[90m─\x1b[0m")).toBe(true);
+  });
+
+  it("returns false for non-border", () => {
+    expect(isParentBorder("hello")).toBe(false);
+  });
+
+  it("returns false for empty string", () => {
+    expect(isParentBorder("")).toBe(false);
+  });
+});
+
+// ── formatKey ───────────────────────────────────────────────────────────────
+
+describe("formatKey", () => {
+  it("formats ctrl+a", () => {
+    expect(formatKey("ctrl+a")).toBe("Ctrl+A");
+  });
+
+  it("formats alt+shift+f", () => {
+    expect(formatKey("alt+shift+f")).toBe("Alt+Shift+F");
+  });
+
+  it("formats cmd as Cmd", () => {
+    expect(formatKey("cmd")).toBe("Cmd");
+  });
+
+  it("formats meta as Cmd", () => {
+    expect(formatKey("meta")).toBe("Cmd");
+  });
+
+  it("uppercases single char", () => {
+    expect(formatKey("a")).toBe("A");
+    expect(formatKey("z")).toBe("Z");
+  });
+
+  it("capitalizes multi-word", () => {
+    expect(formatKey("escape")).toBe("Escape");
+    expect(formatKey("enter")).toBe("Enter");
+  });
+
+  it("returns that key for undefined", () => {
+    expect(formatKey(undefined)).toBe("that key");
+  });
+});