@pi-archimedes/core 2.5.0 → 2.6.2

package/README.md

@@ -1,51 +1,60 @@
 # @pi-archimedes/core
 
-The visual foundation and shared infrastructure for pi-archimedes.
+**A terminal worth spending your day in — plus the plumbing that keeps the rest of the suite talking.**
 
-Core is what you see first — the animated splash screen, the framed editor, and styled thinking blocks. It is also the invisible glue: an event bus that lets packages talk to each other, shared text and color utilities, and a settings system. Install it standalone for polished chrome, or let the meta package include it automatically.
-
-## What you get
-
-- **Animated splash screen** — configurable reveal animations (9 styles) that set the tone when Pi starts
-- **Framed editor** — custom editor component with double-press quit guard
-- **Styled thinking blocks** — configurable label text, color, and muted theme option; optional code block unindenting
-- **Event bus** — shared pub/sub channel that lets packages communicate (subagent costs → footer, subagent questions → ask, etc.)
-- **Shared utilities** — text truncation/width calculation, color helpers, config loading, settings I/O, and startup profiling
+Core is the face of every session: the animated splash screen on launch, the framed editor where you type, the border spinner that works while the agent works, and clean, labelled thinking blocks. Under the surface it runs the shared event bus through which the other components pass costs, todos, and questions — and the text, colour, and settings utilities they all build on.
 
 ## Install
 
+Standalone:
+
 ```bash
 pi install npm:@pi-archimedes/core
 ```
 
-Or install full meta package:
+Or the full suite instead (which includes core and the ten optional components):
 
 ```bash
 pi install npm:pi-archimedes
 ```
 
-## Usage
+New to Pi? Pi itself is a one-time global install and needs Node.js ≥ 22.19.0:
+
+```bash
+npm install -g --ignore-scripts @earendil-works/pi-coding-agent
+```
+
+After installing Pi, choose one installation command above, then `cd` into your project and run `pi`. Inside the session, `/login` signs you into a supported provider and `/model` picks a model; the full walkthrough, including API-key setup, is in the repo's [setup section](https://github.com/danielcherubini/pi-archimedes#setup) and Pi's own [quickstart](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/quickstart.md). A session that's already running picks up the extension with `/reload`.
 
-Core works automatically when Pi starts. It sets the session header, editor frame, and thinking block renderer automatically. There are no manual commands or tools to call.
+## What you get
 
-For configuration:
-- When using the meta package, run `/archimedes` to access the settings panel.
-- For standalone installs, edit `archimedes.core` in `~/.pi/agent/settings.json`.
+- **Splash screen** — an animated greeting when the session launches, in one of nine reveal styles (`diagonal`, `top-right`, `bottom-left`, `bottom-right`, `center-out`, `wave`, `horizontal`, `vertical`, `vertical-up`).
+- **Framed editor** — your input in a clean bordered frame, with a double-press guard on the quit key (`Ctrl+C` by default) so a stray keystroke doesn't end the session.
+- **Working spinner on the border** — one of ten animating styles (`pendulum`, `typing`, `pulse`, `marquee`, `wave-rows`, `columns`, `cascade`, `diagonal-swipe`, `rain`, `sparkle`) traces the editor frame while the agent works, replacing Pi's native "Working" line.
+- **Thinking blocks** — chain-of-thought output gets a consistent label, colour, and layout; `codeUnindent` strips the common indentation so code in reasoning reads flush.
+- **The bus** (`@pi-archimedes/core/bus`) — a global pub/sub event system: `COST_UPDATE`, `ASK_REQUEST`, `TODOS_UPDATE`, `TODOS_CLEAR`… subagent costs flow to the footer through it, subagent todos to the task board, subagent questions to the ask UI.
+- **Shared utilities** — text truncation and width measurement, colour formatting, settings I/O, and startup profiling.
 
 ## Settings
 
-Core reads configuration from the `archimedes.core` namespace in `~/.pi/agent/settings.json`.
+Settings live in `~/.pi/agent/settings.json` under `archimedes.core`. The file is **strict JSON — no comments or trailing commas** (unlike the MCP server config files, which accept both).
 
 | Setting | Type | Default | Description |
 |---------|------|---------|-------------|
-| `mutedTheme` | bool | `false` | Use subdued colors for thinking blocks |
-| `codeUnindent` | bool | `true` | Remove common indentation from code blocks inside thinking sections |
-| `labelText` | string | `Thinking...` | Custom prefix shown before thinking blocks |
-| `labelColor` | string | `255,215,0` | RGB color for the thinking label |
-| `animationStyle` | string | `vertical-up` | Splash animation style (9 options) |
+| `editorSpinBorder` | bool | `true` | Show the animated border spinner while the agent works |
+| `editorSpinStyle` | string | `pendulum` | One of the ten spinner styles |
+| `editorSpinSpeed` | string | `normal` | `slow`, `normal`, or `fast` |
+| `editorSpinLabel` | string | `Working` | Label shown alongside the border spinner |
+| `animationStyle` | string | `vertical-up` | Splash-screen reveal style (the nine styles above) |
+| `labelText` | string | `Thinking...` | Prefix before thinking blocks |
+| `labelColor` | string | `255,215,0` | RGB string for the thinking label |
+| `codeUnindent` | bool | `true` | Strip common indentation from code blocks in thinking sections |
+| `mutedTheme` | bool | `false` | Stored, but **not yet effective** — the current thinking renderer doesn't consult it, so treat it as a pending toggle |
+
+In the suite, `/archimedes` offers panel controls for the settings that have them; `/reload` applies any that are read at startup.
 
-## Integration
+## Part of the suite
 
-Core is auto-included by the `pi-archimedes` meta package. All other archimedes packages depend on `@pi-archimedes/core` for the event bus, chrome elements, and utilities. Standalone installation provides the visual chrome and bus without the other archimedes features.
+In [pi-archimedes](https://github.com/danielcherubini/pi-archimedes), core is always registered — it isn't one of the `/plugins` toggles — and it underpins what the other components share: the bus that feeds subagent costs to the footer, subagent todos to the task board, and subagent questions to the ask UI, plus the chrome and colour utilities the TUIs use. The diff renderer is standalone and does not depend on core's chrome — it only shares the suite when it loads.
 
-← Back to [pi-archimedes](../../README.md)
+← [Back to pi-archimedes](https://github.com/danielcherubini/pi-archimedes)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-archimedes/core",
-  "version": "2.5.0",
+  "version": "2.6.2",
   "type": "module",
   "keywords": [
     "pi-package"
@@ -27,8 +27,8 @@
     "@earendil-works/pi-tui": ">=0.1.0"
   },
   "devDependencies": {
-    "@earendil-works/pi-coding-agent": "^0.84.4",
-    "@earendil-works/pi-tui": "^0.84.4",
+    "@earendil-works/pi-coding-agent": "^0.85.1",
+    "@earendil-works/pi-tui": "^0.85.1",
     "typescript": "^6.0.0"
   },
   "pi": {

package/src/chrome.test.ts

@@ -0,0 +1,53 @@
+import { describe, it, expect } from "vitest";
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { resolvePalette } from "./chrome.js";
+
+// ── Mock theme (mirrors the stubTheme / safeThemeColor assertion style) ──
+
+// theme.fg per safeThemeColor: a key missing from `defined` resolves to
+// undefined, exercising the fallback chain. Each available key answers
+// with its own marker so tests can tell which key won.
+function makeTheme(defined: Record<string, string>): Theme {
+  return {
+    fg: (key: string, text: string) => {
+      const marker = defined[key];
+      return marker === undefined ? undefined : `\x1b[${marker}m${text}\x1b[0m`;
+    },
+  } as unknown as Theme;
+}
+
+// ── spin palette entry ───────────────────────────────────────────────────
+
+describe("resolvePalette spin", () => {
+  it("wraps in the accent fg when the theme provides accent (and differs from prefix)", () => {
+    const p = resolvePalette(
+      makeTheme({
+        accent: "38;2;1;2;3",
+        borderMuted: "38;2;9;9;9",
+        border: "38;2;9;9;99",
+      }),
+    );
+    // accent wins for spin ...
+    expect(p.spin("t")).toBe("\x1b[38;2;1;2;3mt\x1b[0m");
+    // ... while prefix stays on borderMuted
+    expect(p.prefix("t")).toBe("\x1b[38;2;9;9;9mt\x1b[0m");
+    expect(p.spin("t")).not.toBe(p.prefix("t"));
+  });
+
+  it("falls back to borderMuted when accent is unavailable", () => {
+    const p = resolvePalette(
+      makeTheme({
+        borderMuted: "38;2;9;9;9",
+        border: "38;2;9;9;99",
+      }),
+    );
+    expect(p.spin("t")).toBe("\x1b[38;2;9;9;9mt\x1b[0m");
+    expect(p.spin("t")).toBe(p.prefix("t"));
+  });
+
+  it("falls back to the neutral gray when neither is available", () => {
+    const p = resolvePalette(makeTheme({}));
+    // Same fallback the safeThemeColor chain already uses for borderMuted/border
+    expect(p.spin("t")).toBe("\x1b[38;2;74;74;74mt\x1b[0m");
+  });
+});

package/src/chrome.ts

@@ -29,6 +29,7 @@ export interface PanePalette {
   panelEdge: string;
   frame(text: string): string;
   prefix(text: string): string;
+  spin(text: string): string;
   time(text: string): string;
   hint(text: string): string;
 }
@@ -80,6 +81,7 @@ export function resolvePalette(theme: Theme): PanePalette {
     panelEdge: bgToFgAnsi(panelBg),
     frame: (t) => safeThemeColor(theme, ["borderMuted", "border"], t),
     prefix: (t) => safeThemeColor(theme, ["borderMuted", "border"], t),
+    spin: (t) => safeThemeColor(theme, ["accent", "borderMuted"], t),
     time: (t) => safeThemeColor(theme, ["muted", "accent"], t),
     hint: (t) => safeThemeColor(theme, ["dim", "muted"], t),
   };

package/src/config.test.ts

@@ -29,6 +29,10 @@ describe("loadCoreConfig", () => {
       labelText: "Thinking...",
       labelColor: "255,215,0",
       animationStyle: "vertical-up",
+      editorSpinBorder: true,
+      editorSpinSpeed: "normal",
+      editorSpinLabel: "Working",
+      editorSpinStyle: "pendulum",
     });
   });
 
@@ -65,8 +69,33 @@ describe("DEFAULT_CORE_CONFIG", () => {
       labelText: "Thinking...",
       labelColor: "255,215,0",
       animationStyle: "vertical-up",
+      editorSpinBorder: true,
+      editorSpinSpeed: "normal",
+      editorSpinLabel: "Working",
+      editorSpinStyle: "pendulum",
     });
   });
+
+  it("exposes a speed→multiplier map (slow/normal/fast = 1.5/1/0.6 × native tempo)", async () => {
+    const { SPIN_SPEED_MULT } = await import("./config.js");
+    expect(SPIN_SPEED_MULT).toEqual({ slow: 1.5, normal: 1, fast: 0.6 });
+  });
+
+  it("exposes the SPIN_INTERVALS key set (ten gallery-derived styles)", async () => {
+    const { SPIN_INTERVALS } = await import("./editor/spin.js");
+    expect(Object.keys(SPIN_INTERVALS)).toEqual([
+      "typing",
+      "pulse",
+      "rain",
+      "cascade",
+      "columns",
+      "wave-rows",
+      "diagonal-swipe",
+      "sparkle",
+      "pendulum",
+      "marquee",
+    ]);
+  });
 });
 
 describe("ANIMATION_STYLES", () => {

package/src/config.ts

@@ -19,14 +19,42 @@ export interface CoreConfig {
   labelText: string;
   labelColor: string;
   animationStyle: AnimationStyle;
+  editorSpinBorder: boolean;
+  editorSpinSpeed: "slow" | "normal" | "fast";
+  editorSpinLabel: string;
+  editorSpinStyle: SpinnerStyle;
 }
 
+/** Border-spinner style (the ten gallery-derived variants, all registered in `SPIN_VARIANTS` (`editor/spin.ts`); unknown values normalize to `typing` via `normalizeSpinnerStyle`). */
+export type SpinnerStyle =
+  | "typing"
+  | "pulse"
+  | "rain"
+  | "cascade"
+  | "columns"
+  | "wave-rows"
+  | "diagonal-swipe"
+  | "sparkle"
+  | "pendulum"
+  | "marquee";
+
 export const DEFAULT_CORE_CONFIG: CoreConfig = {
   mutedTheme: false,
   codeUnindent: true,
   labelText: "Thinking...",
   labelColor: "255,215,0",
   animationStyle: "vertical-up",
+  editorSpinBorder: true,
+  editorSpinSpeed: "normal",
+  editorSpinLabel: "Working",
+  editorSpinStyle: "pendulum",
+};
+
+/** Border-spinner speed setting → the multipliers the `editorSpinSpeed` setting applies to the style's native per-tick interval (SPIN_INTERVALS, `editor/spin.ts` — typing: 120 / 80 / 48 ms). */
+export const SPIN_SPEED_MULT: Record<CoreConfig["editorSpinSpeed"], number> = {
+  slow: 1.5,
+  normal: 1,
+  fast: 0.6,
 };
 
 const NAMESPACE = "archimedes.core";