@pi-archimedes/ui 2.10.4 → 2.11.0

package/src/config.test.ts

@@ -3,11 +3,13 @@ import { describe, it, expect, vi, beforeEach } from "vitest";
 vi.mock("@pi-archimedes/core/settings-io", () => ({
   loadConfig: vi.fn(),
   saveConfig: vi.fn(),
+  readEffectiveSettings: vi.fn(),
 }));
 
 import {
   loadUIConfig,
   saveUIConfig,
+  readQuietStartup,
   DEFAULT_UI_CONFIG,
   ANIMATION_STYLES,
   THINKING_STYLE_VALUES,
@@ -17,7 +19,7 @@ import {
   normalizeToolStyle,
   SPIN_SPEED_MULT,
 } from "./config.js";
-import { loadConfig, saveConfig } from "@pi-archimedes/core/settings-io";
+import { loadConfig, saveConfig, readEffectiveSettings } from "@pi-archimedes/core/settings-io";
 
 describe("loadUIConfig", () => {
   beforeEach(() => {
@@ -43,6 +45,7 @@ describe("loadUIConfig", () => {
       codeUnindent: true,
       labelText: "Thinking...",
       labelColor: "255,215,0",
+      startupSplash: false,
       animationStyle: "vertical-up",
       colorfulLogo: false,
       editorSpinBorder: true,
@@ -75,6 +78,18 @@ describe("saveUIConfig", () => {
     saveUIConfig(config);
     expect(saveConfig).toHaveBeenCalledWith("archimedes.ui", config);
   });
+
+  // The splash toggle is saved by the same whole-object write as every other UI
+  // key, so `/archimedes` turning it on reaches settings.json as
+  // `archimedes.ui.startupSplash` — nothing strips an unknown key on the way.
+  it("persists startupSplash under archimedes.ui", () => {
+    const config = { ...DEFAULT_UI_CONFIG, startupSplash: true };
+    saveUIConfig(config);
+    expect(saveConfig).toHaveBeenCalledWith(
+      "archimedes.ui",
+      expect.objectContaining({ startupSplash: true }),
+    );
+  });
 });
 
 describe("DEFAULT_UI_CONFIG", () => {
@@ -89,6 +104,7 @@ describe("DEFAULT_UI_CONFIG", () => {
       codeUnindent: true,
       labelText: "Thinking...",
       labelColor: "255,215,0",
+      startupSplash: false,
       animationStyle: "vertical-up",
       colorfulLogo: false,
       editorSpinBorder: true,
@@ -98,6 +114,12 @@ describe("DEFAULT_UI_CONFIG", () => {
     });
   });
 
+  // The maintainer's call on the startup splash: keep the code, flip the
+  // default. pi's own startup is what a fresh install sees.
+  it("leaves the startup splash off, so pi's own startup is the default", () => {
+    expect(DEFAULT_UI_CONFIG.startupSplash).toBe(false);
+  });
+
   it("exposes a speed→multiplier map (slow/normal/fast = 1.5/1/0.6)", () => {
     expect(SPIN_SPEED_MULT).toEqual({ slow: 1.5, normal: 1, fast: 0.6 });
   });
@@ -199,3 +221,42 @@ describe("normalizeToolStyle", () => {
     expect(normalizeToolStyle(true)).toBe("Minimal");
   });
 });
+
+// ── readQuietStartup ─────────────────────────────────────────────────
+//
+// pi 1.x's `quietStartup` is what decides how much of the startup screen the
+// splash may draw: `false` = header + details, `"header"` = header alone,
+// `true` = nothing. These are pi's own semantics, mirrored — a value that is
+// not one of the three (including an absent key, whose pi default is `false`)
+// reads as `false`.
+
+describe("readQuietStartup", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  const answering = (settings: unknown) => {
+    vi.mocked(readEffectiveSettings).mockReturnValue(settings as Record<string, unknown>);
+    return readQuietStartup({});
+  };
+
+  it("reads each of the three values pi accepts", () => {
+    expect(answering({ quietStartup: false })).toBe(false);
+    expect(answering({ quietStartup: true })).toBe(true);
+    expect(answering({ quietStartup: "header" })).toBe("header");
+  });
+
+  it("reads false when the key is absent or unusable", () => {
+    expect(answering({})).toBe(false);
+    expect(answering({ quietStartup: "false" })).toBe(false);
+    expect(answering({ quietStartup: 0 })).toBe(false);
+    expect(answering({ quietStartup: null })).toBe(false);
+  });
+
+  it("passes the pi handle through — getSettings() lives on ExtensionAPI, not the context", () => {
+    const pi = {};
+    vi.mocked(readEffectiveSettings).mockReturnValue({});
+    readQuietStartup(pi);
+    expect(readEffectiveSettings).toHaveBeenCalledWith(pi);
+  });
+});

package/src/config.ts

@@ -1,4 +1,4 @@
-import { loadConfig, saveConfig } from "@pi-archimedes/core/settings-io";
+import { loadConfig, saveConfig, readEffectiveSettings } from "@pi-archimedes/core/settings-io";
 
 export const ANIMATION_STYLES = [
   "diagonal",
@@ -86,6 +86,12 @@ export interface UIConfig {
   codeUnindent: boolean;
   labelText: string;
   labelColor: string;
+  /**
+   * Opt in to the Archimedes startup splash (logo reveal + `[Version]`/`[Models]`
+   * rows). Default **off**: pi owns the startup screen unless the user asks.
+   * See the truth table in `index.ts` for how this and `quietStartup` interact.
+   */
+  startupSplash: boolean;
   animationStyle: AnimationStyle;
   colorfulLogo: boolean;
   editorSpinBorder: boolean;
@@ -106,6 +112,9 @@ export const DEFAULT_UI_CONFIG: UIConfig = {
   codeUnindent: true,
   labelText: "Thinking...",
   labelColor: "255,215,0",
+  // Off by default: the splash stays in the codebase, pi's own startup is what
+  // a user sees unless they turn it on (`/archimedes` → Startup Splash).
+  startupSplash: false,
   animationStyle: "vertical-up",
   colorfulLogo: false,
   editorSpinBorder: true,
@@ -126,6 +135,41 @@ export function loadUIConfig(): UIConfig {
   return loadConfig(NAMESPACE, DEFAULT_UI_CONFIG);
 }
 
+/**
+ * Write the whole `archimedes.ui` namespace (core's `saveConfig` replaces the
+ * section, it does not merge into it), so every key the caller holds lands —
+ * including any this package has not heard of. A new field therefore needs no
+ * handling here: it arrives on the `UIConfig` the `/archimedes` panel hands
+ * back, and `loadUIConfig()` reads it back merged over `DEFAULT_UI_CONFIG` (an
+ * absent key means the default, which is how `startupSplash: false` works for a
+ * settings file written before the key existed).
+ */
 export function saveUIConfig(config: UIConfig): void {
   saveConfig(NAMESPACE, config);
 }
+
+/**
+ * pi's own `quietStartup`, normalised to the three answers pi acts on.
+ *
+ * pi's semantics (`shouldShowStartupHeader()` / `shouldShowStartupDetails()` in
+ * its interactive mode): the startup header is hidden only by `true`; the
+ * startup *details* — the `Model scope:` line and the loaded-resource listing —
+ * are shown only by `false`. `"header"` is the middle case: keep the header,
+ * drop the details. Anything else, including an absent key (pi's default is
+ * `false`), reads as `false`.
+ *
+ * Read through `readEffectiveSettings`, so a project-scoped `quietStartup` and
+ * any in-process override count — the same object pi applies. One input is out
+ * of reach: pi's verbose-startup CLI flag overrides the setting for pi's own
+ * rendering and is not exposed to extensions, so on such a run the splash is
+ * quieter than pi's output. Taking the `pi` handle (not `ctx`) is required —
+ * `getSettings()` lives on `ExtensionAPI`.
+ *
+ * Only consulted when `startupSplash` is on (see the gate in `index.ts`): with
+ * the splash off this package installs no header at all and has no use for the
+ * answer.
+ */
+export function readQuietStartup(pi: unknown): boolean | "header" {
+  const value = (readEffectiveSettings(pi) as { quietStartup?: unknown }).quietStartup;
+  return value === true ? true : value === "header" ? "header" : false;
+}

package/src/editor/index.test.ts

@@ -20,7 +20,11 @@ const widthProbe = vi.hoisted(() => ({
   probe: (s: string): number => s.length,
 }));
 
-vi.mock("@earendil-works/pi-tui", () => ({
+// `foregroundAnsi` comes from the real module: `core/chrome.ts` asks the host's
+// own colour emitter to turn a token's `Color` into a foreground escape, so
+// stubbing it here would make the slab-colour assertions below tautological.
+vi.mock("@earendil-works/pi-tui", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("@earendil-works/pi-tui")>()),
   truncateToWidth: (s: string, _w: number, _pad?: string, _incl?: boolean) => s,
   isKeyRelease: () => false,
   visibleWidth: (s: string) => widthProbe.probe!(s),
@@ -95,6 +99,8 @@ const stubTheme = {
 
 interface ConstructOpts {
   spin?: boolean;
+  /** The theme `getTheme()` hands the palette resolver; defaults to `stubTheme`. */
+  theme?: Theme;
   /** The `editorSpinSpeed` setting; × multiplies the style's native per-tick tempo (× 1.5 / × 1 / × 0.6), 32 ms tick floor. */
   spinSpeed?: "slow" | "normal" | "fast";
   /** The `editorSpinStyle` setting (raw setting string tolerated; a style not registered in `SPIN_VARIANTS` yet (batch 4) normalizes to typing frames — the fallback, which stays typing even though the default setting is now pendulum). */
@@ -123,7 +129,7 @@ function makeEditor(opts: ConstructOpts = {}): {
     ? opts.onSpinInterval
     : vi.fn();
   const editor = new HephaestusEditor(tui, editorTheme, keybindings, {
-    getTheme: () => stubTheme,
+    getTheme: () => opts.theme ?? stubTheme,
     isIdle: () => (seq.length > 0 ? (seq.shift() as boolean) : true),
     shutdown: vi.fn(),
     spin: opts.spin,
@@ -818,3 +824,113 @@ describe("EAW terminal fallback", () => {
     }
   });
 });
+
+// ── 6. Edge rows: a cushion in the panel's own colour, or nothing at all ───
+
+describe("editor edge rows", () => {
+  /**
+   * The shape pi 1.2.0's DEFAULT `system` theme answers with on a terminal that
+   * did not report a background (`indexedColors` in pi's system-theme.js gives
+   * every panel token `""`, and the neutral foreground tokens `""` plus SGR 2):
+   * measured against the installed package, not written from the prose —
+   * `getBgAnsi("userMessageBg")` is `"\x1b[49m"` and `getFgAnsi("borderMuted")`
+   * is `"\x1b[39m\x1b[2m"`. `resolvePalette` reads both as *no colour*, so the
+   * palette hands the editor `panelBg: ""` / `panelEdge: ""`.
+   */
+  const terminalDefaultTheme = {
+    appearance: "dark",
+    fg: (_key: string, text: string) => text,
+    getBgAnsi: () => "\x1b[49m",
+    getFgAnsi: () => "\x1b[39m\x1b[2m",
+  } as unknown as Theme;
+
+  /**
+   * A theme that gives the panel a tint, shaped like the installed dark theme:
+   * `userMessageBg: "#213b49"` — so `theme.colors.userMessageBg` is that rgb —
+   * and a *different* `borderMuted: "#768186"`. Having the two colours far apart
+   * is the point: the slab must pick the panel's own, or the editor grows a grey
+   * rule hugging the text area.
+   */
+  const tintedTheme = {
+    appearance: "dark",
+    fg: (_key: string, text: string) => text,
+    getBgAnsi: (key: string) =>
+      key === "userMessageBg" ? "\x1b[48;2;33;59;73m" : "\x1b[49m",
+    getFgAnsi: (key: string) =>
+      key === "borderMuted" ? "\x1b[38;2;118;129;134m" : "\x1b[39m",
+    colors: { userMessageBg: { kind: "rgb", r: 33, g: 59, b: 73 } },
+    getColorMode: () => "truecolor",
+  } as unknown as Theme;
+
+  /** The panel's own tint and the theme's border, as foreground escapes. */
+  const PANEL_TINT = "\x1b[38;2;33;59;73m";
+  const BORDER_MUTED = "\x1b[38;2;118;129;134m";
+
+  const SLABS = ["▁", "▔"];
+
+  it("paints no slab glyphs when the palette has no edge colour", () => {
+    // `panelEdge: ""` documents "no edge". Prepending nothing to a row of `▁`
+    // does not remove the row: the glyphs then paint in the terminal's OWN
+    // foreground, so the default theme on a dark terminal got bright bars above
+    // and below the editor — the opposite of "no colour".
+    const { editor } = makeEditor({ theme: terminalDefaultTheme });
+    const lines = editor.render(60);
+    for (const line of lines) {
+      for (const slab of SLABS) {
+        expect(line, JSON.stringify(line)).not.toContain(slab);
+      }
+    }
+  });
+
+  it("blanks the rows when the panel IS tinted but the edge has no colour", () => {
+    // The realistic degradation, not the empty-theme case: a modern theme (so a
+    // real panel tint) on a host that cannot render a colour as a foreground.
+    // `panelEdge` is "" while `panelBg` is a colour, so what these rows do is
+    // decided by the edge alone — painting on the body's colour instead would
+    // put a truecolour background behind the glyphs, and dropping the rows
+    // outright would break the frame's height.
+    const { colors: _noColors, getColorMode: _noMode, ...noForeground } =
+      tintedTheme as unknown as Record<string, unknown>;
+    const lines = makeEditor({
+      theme: noForeground as unknown as Theme,
+    }).editor.render(60);
+    expect(plain(lines[0]!)).toBe(" ".repeat(60));
+    expect(plain(lines[lines.length - 1]!)).toBe(" ".repeat(60));
+    for (const slab of SLABS) {
+      expect(lines[0]!).not.toContain(slab);
+      expect(lines[lines.length - 1]!).not.toContain(slab);
+    }
+    // The body kept its tint: only the cushion gave up.
+    expect(lines[1]).toContain("\x1b[48;2;33;59;73m");
+  });
+
+  it("paints the slab rows in the panel's OWN colour, so they vanish into the panel", () => {
+    const { editor } = makeEditor({ theme: tintedTheme });
+    const lines = editor.render(60);
+    // The slab sits directly against the panel body, so painted in the panel's
+    // own tint it is invisible by construction — the colour cushion it was
+    // invented for.
+    expect(lines[0]).toContain(PANEL_TINT);
+    expect(lines[lines.length - 1]).toContain(PANEL_TINT);
+    // And NOT in the border token, which is what turned the cushion into a
+    // visible grey rule hugging the text area.
+    expect(lines[0]).not.toContain(BORDER_MUTED);
+    expect(lines[lines.length - 1]).not.toContain(BORDER_MUTED);
+    // The colour source is not allowed to move anything: same glyphs, same run.
+    expect(plain(lines[0]!)).toBe("▁".repeat(60));
+    expect(plain(lines[lines.length - 1]!)).toBe("▔".repeat(60));
+  });
+
+  it("keeps the row count identical either way (blank row, not a removed row)", () => {
+    const painted = makeEditor({ theme: tintedTheme }).editor.render(60);
+    const blank = makeEditor({ theme: terminalDefaultTheme }).editor.render(60);
+    // The frame's height is a layout contract: the edge rows go blank, they do
+    // not disappear.
+    expect(blank).toHaveLength(painted.length);
+    expect(plain(blank[0]!)).toBe(" ".repeat(60));
+    expect(plain(blank[blank.length - 1]!)).toBe(" ".repeat(60));
+    // Which row carries the frame is part of the same contract.
+    expect(plain(painted[1]!).trim().startsWith("┌")).toBe(true);
+    expect(plain(blank[1]!).trim().startsWith("┌")).toBe(true);
+  });
+});

package/src/editor/index.ts

@@ -22,6 +22,7 @@ import {
   resolvePalette,
 } from "@pi-archimedes/core/chrome";
 import { isParentBorder, formatKey } from "@pi-archimedes/core/text";
+import { diag, describeError } from "@pi-archimedes/core/log";
 import { SPIN_INTERVALS, BorderTypeSpinner } from "./spin.js";
 export { spinFrame } from "./spin.js";
 import { pickQuip, QUIP_ROTATION_MAX_SECS, QUIP_ROTATION_MIN_SECS } from "./spin-quips.js";
@@ -82,6 +83,19 @@ export class HephaestusEditor extends CustomEditor {
       onSpinInterval,
     }: {
       getTheme: () => Theme;
+      /**
+       * Whether the agent is idle right now — the only source of busy/idle
+       * state for the spinner and the quip. It is injected rather than read
+       * from a stored renderer so a screen-mode switch cannot strand it.
+       *
+       * pi 1.2.0 semantics, checked rather than assumed: `ctx.isIdle()` turns
+       * false at `before_agent_start`, i.e. when a run begins — including one
+       * an extension started with `pi.sendMessage(…, { triggerTurn: true })` —
+       * not when the first token arrives. That is the *Busy episode* boundary
+       * in `CONTEXT.md` (idle → working → idle), so the spinner starting on the
+       * run's first tick is what the term promises; there is no early-start
+       * bug to correct here.
+       */
       isIdle: () => boolean;
       shutdown: () => void;
       /** Type a 4-cell spinner window into the editor's top border while the agent is busy (the animation mechanism lives in `BorderTypeSpinner`, `./spin.js`): the style-configured 4-cell window (the gallery-derived styles in `SPIN_VARIANTS` — the 2×4 braille dot block (⠁ → ⣿, Unicode chart order, `typing`) grows cell-by-cell left→right — each cell walking the 8 stages in 2-step line pairs (⠁⠉/⠋⠛/⠟⠿/⡿⣿) — then holds, clears, repeats (in EAW terminals the stage set falls back to the width-1 shading ░ → █; raw setting strings are tolerated — unknown names normalize to typing frames). */
@@ -368,12 +382,29 @@ export class HephaestusEditor extends CustomEditor {
         return p.panelBg + pad + patched + pad + RESET;
       };
 
-      const topEdge = p.panelEdge + "▁".repeat(width) + RESET;
-      const botEdge = p.panelEdge + "▔".repeat(width) + RESET;
+      // The slab rows are the panel's own colour, extending its tint flush to
+      // the frame (see `resolvePalette`: the edge is the panel token asked for
+      // as a foreground, never a border token — a border colour here is a
+      // visible rule hugging the text area).
+      //
+      // No edge colour means the theme declined a panel colour entirely (a
+      // terminal-default token) or cannot answer its own token as a foreground.
+      // Either way an un-prefixed row of `▁`/`▔` would paint those glyphs in the
+      // terminal's own FOREGROUND — a hard, bright bar above and below the
+      // editor (what pi's default `system` theme on a terminal that reported no
+      // background produces). No colour, no slab: the rows go blank rather than
+      // disappearing, because the frame's height is a layout contract.
+      const edgeRow = (glyph: string): string =>
+        p.panelEdge ? p.panelEdge + glyph.repeat(width) + RESET : " ".repeat(width);
+      const topEdge = edgeRow("▁");
+      const botEdge = edgeRow("▔");
 
       return [topEdge, ...raw.map(wrap), botEdge];
     } catch (e) {
-      console.error("HephaestusEditor render error:", e);
+      // Re-thrown, so pi's own error handling still sees it — and logged with
+      // its stack, because a console write here would land inside the frame
+      // being rendered and the log is the only record that survives.
+      diag("ui", `HephaestusEditor render error: ${describeError(e)}`);
       throw e;
     }
   }

package/src/editor/spin-quips.ts

@@ -20,7 +20,7 @@ export const SPIN_QUIPS: readonly string[] = Object.freeze([
   "Collapsing quantum wavefunctions just by looking at them...",
   "Hunting for rogue gravitons inside the server rack...",
   "Paging memory to disk because we refused to optimize...",
-  "Optimizing the optimizer so it can optimize faster...",
+  "Optimizing the optimizer so it can optimize optimially...",
   "Searching the entire keyboard for the legendary 'Any' key...",
   "Reticulating multi-dimensional splines...",
   "Running gradient ascent until we reach enlightenment...",