@prometheus-ai/agent 0.5.4 → 0.5.8

package/src/modes/setup-wizard/index.ts

@@ -1,4 +1,5 @@
 import type { Settings } from "../../config/settings";
+import { CURRENT_SETUP_VERSION } from "../setup-version";
 import type { InteractiveModeContext } from "../types";
 import { glyphSetupScene } from "./scenes/glyph";
 import { providersSetupScene } from "./scenes/providers";
@@ -8,14 +9,14 @@ import { SetupWizardComponent } from "./wizard-overlay";
 
 export type { SetupScene, SetupSceneController, SetupSceneHost, SetupSceneResult } from "./scenes/types";
 
+export { CURRENT_SETUP_VERSION };
+
 export const ALL_SCENES = [
 	providersSetupScene,
 	glyphSetupScene,
 	themeSetupScene,
 ] as const satisfies readonly SetupScene[];
 
-export const CURRENT_SETUP_VERSION = ALL_SCENES.reduce((max, scene) => Math.max(max, scene.minVersion), 0);
-
 export interface SetupSceneSelectionOptions {
 	resuming?: boolean;
 	isTTY?: boolean;
@@ -64,9 +65,15 @@ export async function markSetupWizardComplete(
 	await settings.flush();
 }
 
+export interface RunSetupWizardOptions {
+	markComplete?: boolean;
+	playWelcomeIntro?: boolean;
+}
+
 export async function runSetupWizard(
 	ctx: InteractiveModeContext,
 	scenes: readonly SetupScene[] = ALL_SCENES,
+	options: RunSetupWizardOptions = {},
 ): Promise<void> {
 	if (scenes.length === 0) return;
 	const component = new SetupWizardComponent(ctx, scenes);
@@ -75,14 +82,19 @@ export async function runSetupWizard(
 		maxHeight: "100%",
 		anchor: "top-left",
 		margin: 0,
+		fullscreen: true,
 	});
 	try {
 		await component.run();
-		await markSetupWizardComplete(ctx.settings);
+		if (options.markComplete !== false) {
+			await markSetupWizardComplete(ctx.settings);
+		}
 	} finally {
 		component.dispose();
 		ctx.ui.setFocus(component);
 		overlay.hide();
 	}
-	ctx.playWelcomeIntro();
+	if (options.playWelcomeIntro !== false) {
+		ctx.playWelcomeIntro();
+	}
 }

package/src/modes/setup-wizard/lazy.ts

@@ -0,0 +1,16 @@
+import type { InteractiveModeContext } from "../types";
+
+export async function runProviderSetupWizard(ctx: InteractiveModeContext): Promise<void> {
+	// Keep the full setup wizard behind the existing cold-start boundary; a static
+	// import here would load provider/OAuth/search/theme setup deps on every TUI startup.
+	const { ALL_SCENES, runSetupWizard } = await import("./index");
+	const providersScene = ALL_SCENES.find(scene => scene.id === "providers");
+	if (!providersScene) {
+		ctx.showError("Provider setup is unavailable.");
+		return;
+	}
+	await runSetupWizard(ctx, [providersScene], {
+		markComplete: false,
+		playWelcomeIntro: false,
+	});
+}

package/src/modes/setup-wizard/scenes/glyph.ts

@@ -1,4 +1,4 @@
-import { type SelectItem, SelectList } from "@prometheus-ai/tui";
+import { type SelectItem, SelectList, type SgrMouseEvent } from "@prometheus-ai/tui";
 import { getSelectListTheme, type SymbolPreset, setSymbolPreset, theme } from "../../theme/theme";
 import type { SetupScene, SetupSceneController, SetupSceneHost } from "./types";
 
@@ -29,6 +29,8 @@ class GlyphSceneController implements SetupSceneController {
 	#selectList: SelectList;
 	#previewRequest = 0;
 	#committing = false;
+	/** Render line where the select list begins. */
+	#listRowStart = 0;
 
 	constructor(private readonly host: SetupSceneHost) {
 		this.#selectList = new SelectList(GLYPH_ITEMS, GLYPH_ITEMS.length, getSelectListTheme());
@@ -60,12 +62,28 @@ class GlyphSceneController implements SetupSceneController {
 		this.#selectList.handleInput(data);
 	}
 
-	render(width: number): string[] {
-		return [
-			theme.fg("muted", "If a row shows boxes, tofu, or misaligned icons, pick another."),
-			"",
-			...this.#selectList.render(width),
-		];
+	/** Wheel moves the highlight (live preview); hover lights the row under the pointer; click confirms it. */
+	routeMouse(event: SgrMouseEvent, line: number, _col: number): void {
+		if (this.#committing) return;
+		if (event.wheel !== null) {
+			this.#selectList.handleWheel(event.wheel);
+			return;
+		}
+		const index = this.#selectList.hitTest(line - this.#listRowStart);
+		if (event.motion) {
+			this.#selectList.setHoverIndex(index ?? null);
+			return;
+		}
+		if (event.leftClick && index !== undefined) {
+			this.#selectList.clickItem(index);
+		}
+	}
+
+	render(width: number): readonly string[] {
+		const lines = [theme.fg("muted", "If a row shows boxes, tofu, or misaligned icons, pick another."), ""];
+		this.#listRowStart = lines.length;
+		lines.push(...this.#selectList.render(width));
+		return lines;
 	}
 
 	async #commit(preset: SymbolPreset): Promise<void> {

package/src/modes/setup-wizard/scenes/providers.ts

@@ -1,27 +1,28 @@
-import { TabBar } from "@prometheus-ai/tui";
+import { type SgrMouseEvent, TabBar } from "@prometheus-ai/tui";
 import { getTabBarTheme } from "../../shared";
-import { ChannelsTab } from "./channels";
 import { SignInTab } from "./sign-in";
 import type { SetupScene, SetupSceneController, SetupSceneHost, SetupTab } from "./types";
 import { WebSearchTab } from "./web-search";
 
 /**
- * Tabbed connection setup scene. Composes independent panels (model sign-in,
- * web search, channels) behind a {@link TabBar}; the active panel owns
+ * Tabbed "Set up your providers" scene. Composes independent panels (model
+ * sign-in, web search) behind a {@link TabBar}; the active panel owns
  * rendering and input, while modal panels (e.g. an in-flight OAuth login)
  * temporarily suppress tab switching.
  */
 class ProvidersSceneController implements SetupSceneController {
-	title = "Set up your connections";
-	subtitle = "Sign in, pick web search, and configure channels. Press Esc when you're done.";
+	title = "Set up your providers";
+	subtitle = "Sign in and pick a web search provider. Press Esc when you're done.";
 
 	#tabs: SetupTab[];
 	#tabBar: TabBar;
+	/** Lines the tab bar occupied in the last render (body starts one blank line below). */
+	#tabRowCount = 1;
 
 	constructor(host: SetupSceneHost) {
-		this.#tabs = [new SignInTab(host), new WebSearchTab(host), new ChannelsTab(host)];
+		this.#tabs = [new SignInTab(host), new WebSearchTab(host)];
 		this.#tabBar = new TabBar(
-			"Connections",
+			"Providers",
 			this.#tabs.map(tab => ({ id: tab.id, label: tab.label })),
 			getTabBarTheme(),
 		);
@@ -53,8 +54,40 @@ class ProvidersSceneController implements SetupSceneController {
 		tab.handleInput(data);
 	}
 
-	render(width: number): string[] {
-		return [...this.#tabBar.render(width), "", ...this.#activeTab().render(width)];
+	/**
+	 * Hit-test mouse reports against the last render: rows inside the tab bar
+	 * hover/switch tabs (suppressed while the active panel is modal, matching
+	 * keyboard tab cycling); everything else forwards to the active panel at
+	 * panel-local coordinates. Wheel always goes to the panel so scrolling
+	 * works regardless of pointer position.
+	 */
+	routeMouse(event: SgrMouseEvent, line: number, col: number): void {
+		const tab = this.#activeTab();
+		if (event.wheel === null && line >= 0 && line < this.#tabRowCount) {
+			if (tab.modal) return;
+			const hit = this.#tabBar.tabAt(line, col);
+			if (event.motion) {
+				this.#tabBar.setHoverTab(hit && !hit.muted ? hit.id : null);
+			} else if (event.leftClick && hit) {
+				this.#tabBar.selectTab(hit.id);
+			}
+			return;
+		}
+		if (event.motion) this.#tabBar.setHoverTab(null);
+		const bodyLine = line - this.#tabRowCount - 1;
+		if (tab.routeMouse) {
+			tab.routeMouse(event, bodyLine, col);
+			return;
+		}
+		if (event.wheel !== null && !tab.modal) {
+			tab.handleInput(event.wheel === -1 ? "\x1b[A" : "\x1b[B");
+		}
+	}
+
+	render(width: number): readonly string[] {
+		const tabLines = this.#tabBar.render(width);
+		this.#tabRowCount = tabLines.length;
+		return [...tabLines, "", ...this.#activeTab().render(width)];
 	}
 
 	dispose(): void {
@@ -64,7 +97,7 @@ class ProvidersSceneController implements SetupSceneController {
 
 export const providersSetupScene: SetupScene = {
 	id: "providers",
-	title: "Set up your connections",
-	minVersion: 3,
+	title: "Set up your providers",
+	minVersion: 1,
 	mount: host => new ProvidersSceneController(host),
 };

package/src/modes/setup-wizard/scenes/sign-in.ts

@@ -1,20 +1,12 @@
 import type { AuthStorage } from "@prometheus-ai/ai";
-import type { OAuthProvider } from "@prometheus-ai/ai/utils/oauth/types";
-import { Input, matchesKey, wrapTextWithAnsi } from "@prometheus-ai/tui";
+import { PASTE_CODE_LOGIN_PROVIDERS } from "@prometheus-ai/ai";
+import type { OAuthProvider } from "@prometheus-ai/ai/oauth/types";
+import { Input, matchesKey, type SgrMouseEvent, wrapTextWithAnsi } from "@prometheus-ai/tui";
 import { getAgentDbPath } from "@prometheus-ai/utils";
 import { OAuthSelectorComponent } from "../../components/oauth-selector";
 import { theme } from "../../theme/theme";
 import type { SetupSceneHost, SetupTab } from "./types";
 
-/** Providers whose OAuth flow needs a pasted code/redirect URL rather than a callback server. */
-const CALLBACK_SERVER_PROVIDERS: Partial<Record<OAuthProvider, true>> = {
-	anthropic: true,
-	"openai-codex": true,
-	"gitlab-duo": true,
-	"google-gemini-cli": true,
-	"google-antigravity": true,
-};
-
 function loginUrlLink(url: string): string {
 	return `\x1b]8;;${url}\x07Open login URL\x1b]8;;\x07`;
 }
@@ -43,6 +35,8 @@ export class SignInTab implements SetupTab {
 	#loginAbort: AbortController | undefined;
 	#loggingInProvider: string | undefined;
 	#disposed = false;
+	/** Render line where the provider selector begins. */
+	#selectorRowStart = 2;
 
 	constructor(private readonly host: SetupSceneHost) {
 		this.#authStorage = host.ctx.session.modelRegistry.authStorage;
@@ -76,12 +70,19 @@ export class SignInTab implements SetupTab {
 		this.#selector.handleInput(data);
 	}
 
-	render(width: number): string[] {
+	/** Forward mouse to the provider selector; pointer is inert during an active login or code prompt. */
+	routeMouse(event: SgrMouseEvent, line: number, col: number): void {
+		if (this.#loggingInProvider || this.#prompt) return;
+		this.#selector.routeMouse(event, line - this.#selectorRowStart, col);
+	}
+
+	render(width: number): readonly string[] {
 		const lines: string[] = [];
 		if (this.#loggingInProvider) {
 			lines.push(theme.bold(`Signing in to ${this.#loggingInProvider}`));
 		} else {
 			lines.push(theme.fg("muted", "Pick a provider to sign in — you can connect more than one."), "");
+			this.#selectorRowStart = lines.length;
 			lines.push(...this.#selector.render(width));
 		}
 
@@ -119,7 +120,7 @@ export class SignInTab implements SetupTab {
 
 	async #login(providerId: string): Promise<void> {
 		if (this.#loggingInProvider || this.#disposed) return;
-		const useManualInput = CALLBACK_SERVER_PROVIDERS[providerId as OAuthProvider] === true;
+		const useManualInput = PASTE_CODE_LOGIN_PROVIDERS.has(providerId);
 		this.#selector.stopValidation();
 		this.#loggingInProvider = providerId;
 		this.#statusLines = [theme.fg("dim", "Starting OAuth flow…")];

package/src/modes/setup-wizard/scenes/splash.ts

@@ -189,7 +189,7 @@ export function renderSetupSplash(width: number, height: number, elapsedMs: numb
 /** Centered fallback for windows too small to hold the full scene. */
 function renderCompactSplash(width: number, height: number, phase: number, shine: ShineConfig): string[] {
 	const art = height >= 14 ? LARGE_LOGO : PROMETHEUS_LOGO;
-	const content = [...gradientLogo(art, phase, shine), "", theme.bold("Prometheus")];
+	const content = [...gradientLogo(art, phase, shine), "", theme.bold("O h   M y   P i")];
 	const start = Math.max(0, Math.floor((height - content.length) / 2));
 	const lines: string[] = [];
 	for (let y = 0; y < height; y++) {

package/src/modes/setup-wizard/scenes/theme.ts

@@ -1,4 +1,11 @@
-import { padding, type SelectItem, SelectList, truncateToWidth, visibleWidth } from "@prometheus-ai/tui";
+import {
+	padding,
+	type SelectItem,
+	SelectList,
+	type SgrMouseEvent,
+	truncateToWidth,
+	visibleWidth,
+} from "@prometheus-ai/tui";
 import {
 	enableAutoTheme,
 	getAvailableThemes,
@@ -89,6 +96,8 @@ class ThemeSceneController implements SetupSceneController {
 	#message: string | undefined;
 	#previewRequest = 0;
 	#disposed = false;
+	/** Render line where the select list began, or -1 while it is not shown. */
+	#listRowStart = -1;
 	readonly #originalTheme = getCurrentThemeName();
 	readonly #originalSymbolPreset: SymbolPreset;
 	readonly #originalColorBlindMode: boolean;
@@ -117,7 +126,23 @@ class ThemeSceneController implements SetupSceneController {
 		this.#selectList.handleInput(data);
 	}
 
-	render(width: number): string[] {
+	/** Wheel moves the highlight (live preview); hover lights the row under the pointer; click confirms it. */
+	routeMouse(event: SgrMouseEvent, line: number, _col: number): void {
+		if (event.wheel !== null) {
+			this.#selectList.handleWheel(event.wheel);
+			return;
+		}
+		const index = this.#listRowStart >= 0 ? this.#selectList.hitTest(line - this.#listRowStart) : undefined;
+		if (event.motion) {
+			this.#selectList.setHoverIndex(index ?? null);
+			return;
+		}
+		if (event.leftClick && index !== undefined) {
+			this.#selectList.clickItem(index);
+		}
+	}
+
+	render(width: number): readonly string[] {
 		const lines = [
 			theme.fg("muted", "Theme changes preview live. Nothing is saved until you press Enter."),
 			this.#mode === "all"
@@ -128,8 +153,10 @@ class ThemeSceneController implements SetupSceneController {
 			"",
 		];
 		if (this.#loadingAllThemes) {
+			this.#listRowStart = -1;
 			lines.push(theme.fg("dim", "Loading themes…"));
 		} else {
+			this.#listRowStart = lines.length;
 			lines.push(...this.#selectList.render(width));
 		}
 		if (this.#message) {

package/src/modes/setup-wizard/scenes/types.ts

@@ -1,4 +1,4 @@
-import type { Component } from "@prometheus-ai/tui";
+import type { Component, SgrMouseEvent } from "@prometheus-ai/tui";
 import type { InteractiveModeContext } from "../../types";
 
 export type SetupSceneResult = "done" | "skipped";
@@ -17,6 +17,13 @@ export interface SetupSceneController extends Component {
 	onMount?(): void | Promise<void>;
 	onUnmount?(): void;
 	dispose?(): void;
+	/**
+	 * Route an SGR mouse report (tracking is on while the wizard holds the
+	 * alternate screen). `line`/`col` are 0-based within this controller's
+	 * last rendered output. When absent, the wizard falls back to synthesizing
+	 * arrow keys from wheel notches.
+	 */
+	routeMouse?(event: SgrMouseEvent, line: number, col: number): void;
 }
 
 /**
@@ -31,11 +38,13 @@ export interface SetupTab {
 	 * login). The parent scene MUST NOT switch tabs or finish while modal.
 	 */
 	readonly modal: boolean;
-	render(width: number): string[];
+	render(width: number): readonly string[];
 	handleInput(data: string): void;
 	invalidate(): void;
 	/** Called when the tab becomes active (including initial mount). */
 	onActivate?(): void;
+	/** Mouse routing at tab-local coordinates; see {@link SetupSceneController.routeMouse}. */
+	routeMouse?(event: SgrMouseEvent, line: number, col: number): void;
 	dispose(): void;
 }
 

package/src/modes/setup-wizard/scenes/web-search.ts

@@ -1,4 +1,4 @@
-import { type SelectItem, SelectList, truncateToWidth } from "@prometheus-ai/tui";
+import { type SelectItem, SelectList, type SgrMouseEvent, truncateToWidth } from "@prometheus-ai/tui";
 import { SETTINGS_SCHEMA } from "../../../config/settings-schema";
 import { getSearchProvider, setPreferredSearchProvider } from "../../../web/search/provider";
 import { isSearchProviderPreference, type SearchProviderId } from "../../../web/search/types";
@@ -19,7 +19,8 @@ type Availability = "checking" | boolean;
 /**
  * "Web search" panel: picks the provider the web_search tool should prefer and
  * reports whether the highlighted provider is ready to use given current
- * credentials (env keys or OAuth sign-ins from the Sign in tab).
+ * credentials (env keys or OAuth sign-ins from the Sign in tab) or an
+ * unauthenticated fallback.
  */
 export class WebSearchTab implements SetupTab {
 	readonly id = "web-search";
@@ -30,6 +31,8 @@ export class WebSearchTab implements SetupTab {
 	#availability = new Map<SearchProviderId, Availability>();
 	#status: string[] = [];
 	#disposed = false;
+	/** Render line where the select list begins. */
+	#listRowStart = 0;
 
 	constructor(private readonly host: SetupSceneHost) {
 		this.#list = new SelectList(WEB_SEARCH_ITEMS, MAX_VISIBLE, getSelectListTheme());
@@ -54,6 +57,22 @@ export class WebSearchTab implements SetupTab {
 		this.#list.handleInput(data);
 	}
 
+	/** Wheel moves the highlight; hover lights the row under the pointer; click confirms it. */
+	routeMouse(event: SgrMouseEvent, line: number, _col: number): void {
+		if (event.wheel !== null) {
+			this.#list.handleWheel(event.wheel);
+			return;
+		}
+		const index = this.#list.hitTest(line - this.#listRowStart);
+		if (event.motion) {
+			this.#list.setHoverIndex(index ?? null);
+			return;
+		}
+		if (event.leftClick && index !== undefined) {
+			this.#list.clickItem(index);
+		}
+	}
+
 	invalidate(): void {
 		this.#list.invalidate();
 	}
@@ -62,12 +81,10 @@ export class WebSearchTab implements SetupTab {
 		this.#disposed = true;
 	}
 
-	render(width: number): string[] {
-		const lines = [
-			theme.fg("muted", "Choose the provider the web_search tool should prefer."),
-			"",
-			...this.#list.render(width),
-		];
+	render(width: number): readonly string[] {
+		const lines = [theme.fg("muted", "Choose the provider the web_search tool should prefer."), ""];
+		this.#listRowStart = lines.length;
+		lines.push(...this.#list.render(width));
 		const selected = this.#list.getSelectedItem();
 		if (selected) {
 			lines.push("", ...this.#readinessLines(selected.value).map(line => truncateToWidth(line, width)));
@@ -91,7 +108,7 @@ export class WebSearchTab implements SetupTab {
 			let ready = false;
 			try {
 				const provider = await getSearchProvider(id);
-				ready = await provider.isAvailable(this.host.ctx.session.modelRegistry.authStorage);
+				ready = await provider.isExplicitlyAvailable(this.host.ctx.session.modelRegistry.authStorage);
 			} catch {
 				ready = false;
 			}

package/src/modes/setup-wizard/wizard-overlay.ts

@@ -1,4 +1,4 @@
-import { type Component, matchesKey, padding, truncateToWidth, visibleWidth } from "@prometheus-ai/tui";
+import { type Component, matchesKey, padding, parseSgrMouse, truncateToWidth, visibleWidth } from "@prometheus-ai/tui";
 import { APP_NAME } from "@prometheus-ai/utils";
 import { gradientLogo, PROMETHEUS_LOGO } from "../components/welcome";
 import { theme } from "../theme/theme";
@@ -61,6 +61,8 @@ export class SetupWizardComponent implements Component {
 	#timer: NodeJS.Timeout | undefined;
 	#done = Promise.withResolvers<void>();
 	#disposed = false;
+	/** Screen row where the active scene's body began in the last rendered frame. */
+	#bodyRowStart = 0;
 
 	constructor(
 		readonly ctx: InteractiveModeContext,
@@ -82,11 +84,15 @@ export class SetupWizardComponent implements Component {
 	}
 
 	invalidate(): void {
-		this.#activeScene?.invalidate();
+		this.#activeScene?.invalidate?.();
 	}
 
 	handleInput(data: string): void {
 		if (this.#phase === "done") return;
+		if (data.startsWith("\x1b[<")) {
+			this.#handleMouse(data);
+			return;
+		}
 		if (matchesKey(data, "ctrl+c")) {
 			this.#beginOutro();
 			return;
@@ -116,7 +122,37 @@ export class SetupWizardComponent implements Component {
 		this.#activeScene?.handleInput?.(data);
 	}
 
-	render(width: number): string[] {
+	/**
+	 * Mouse handling for the fullscreen wizard (SGR tracking is on while the
+	 * overlay holds the alternate screen). The frame paints from screen row 0,
+	 * so report coordinates index directly into the last rendered lines: scene
+	 * body rows start at #bodyRowStart, indented by SCENE_MARGIN_X. Scenes
+	 * that implement routeMouse get hit-tested events (wheel, hover, click);
+	 * for the rest a wheel notch falls back to an arrow key. A left click
+	 * advances the splash/outro like Enter. Raw reports never reach scene
+	 * keyboard input.
+	 */
+	#handleMouse(data: string): void {
+		const event = parseSgrMouse(data);
+		if (!event) return;
+		if (this.#phase === "splash" || this.#phase === "outro") {
+			if (!event.leftClick) return;
+			if (this.#phase === "splash") this.#beginScene();
+			else this.#complete();
+			return;
+		}
+		const scene = this.#activeScene;
+		if (!scene) return;
+		if (scene.routeMouse) {
+			scene.routeMouse(event, event.row - this.#bodyRowStart, event.col - SCENE_MARGIN_X);
+			return;
+		}
+		if (event.wheel !== null) {
+			scene.handleInput?.(event.wheel === -1 ? "\x1b[A" : "\x1b[B");
+		}
+	}
+
+	render(width: number): readonly string[] {
 		const safeWidth = Math.max(1, width);
 		const height = Math.max(1, this.ctx.ui.terminal.rows);
 		let lines: string[];
@@ -163,6 +199,7 @@ export class SetupWizardComponent implements Component {
 			header.push(indentLine(theme.fg("muted", subtitle), width, SCENE_MARGIN_X));
 		}
 		header.push("");
+		this.#bodyRowStart = header.length;
 
 		const footer = [
 			"",

package/src/modes/shared.ts

@@ -24,6 +24,8 @@ export function getTabBarTheme(): TabBarTheme {
 		label: (text: string) => theme.bold(theme.fg("accent", text)),
 		activeTab: (text: string) => theme.bold(theme.bg("selectedBg", theme.fg("text", text))),
 		inactiveTab: (text: string) => theme.fg("muted", text),
+		mutedTab: (text: string) => theme.fg("dim", text),
+		hoverTab: (text: string) => theme.bg("selectedBg", theme.fg("text", text)),
 		hint: (text: string) => theme.fg("dim", text),
 	};
 }

package/src/modes/theme/defaults/dark-poimandres.json

@@ -134,7 +134,7 @@
       "icon.loop": "↻",
       "icon.folder": "▸",
       "icon.scratchFolder": "◌",
-      "icon.prometheus": "P",
+      "icon.prometheus": "π",
       "format.bullet": "◦",
       "md.bullet": "◦"
     }

package/src/modes/theme/defaults/light-poimandres.json

@@ -134,7 +134,7 @@
       "icon.loop": "↻",
       "icon.folder": "▸",
       "icon.scratchFolder": "◌",
-      "icon.prometheus": "P",
+      "icon.prometheus": "π",
       "format.bullet": "◦",
       "md.bullet": "◦"
     }

package/src/modes/theme/shimmer.ts

@@ -1,14 +1,20 @@
 import { isSettingsInitialized, settings } from "../../config/settings";
 import type { Theme, ThemeColor } from "./theme";
 
+// ─── Animation velocity ──────────────────────────────────────────────────────
+// Band/head travel speed in border cells per second. Driving position by a fixed
+// velocity — instead of dividing a fixed sweep duration by the (length-derived)
+// period — makes smoothness independent of message length: at the loader's
+// default 30fps redraw cadence the band advances ≤1 cell per frame for any
+// string, so it never visibly steps. Sweep/round-trip durations now scale with
+// length. Keep ≤ the animated redraw fps (loader RENDER_INTERVAL_MS = 1000/30).
+const SHIMMER_SPEED_CELLS_PER_S = 30;
+
 // ─── Classic sweep tunables ──────────────────────────────────────────────────
 const CLASSIC_PADDING = 10;
-const CLASSIC_SWEEP_MS = 1400;
 const CLASSIC_BAND_HALF_WIDTH = 6;
 
 // ─── KITT scanner tunables ───────────────────────────────────────────────────
-// 1.5s round trip ≈ classic 1982 K.I.T.T. scanner cadence (~0.75s per direction).
-const KITT_CYCLE_MS = 1500;
 const KITT_HEAD_HALF = 0.6;
 const KITT_TRAIL_LEN = 7;
 
@@ -103,9 +109,10 @@ function compile(theme: ShimmerTheme, palette: ShimmerPalette): CompiledPalette
 /** Smooth cosine bump sweeping left → right with edge padding. */
 function classicIntensity(time: number, index: number, length: number): number {
 	const period = length + CLASSIC_PADDING * 2;
-	// Fractional position — kept un-floored so the band glides at the host's
-	// frame rate instead of stepping discretely.
-	const pos = ((time % CLASSIC_SWEEP_MS) / CLASSIC_SWEEP_MS) * period;
+	// Fixed-velocity, un-floored band position: advancing at a constant
+	// cells/second (not period / fixed-sweep) keeps the per-frame step ≤1 cell at
+	// the default cadence for any length, so long messages are no steppier.
+	const pos = ((time / 1000) * SHIMMER_SPEED_CELLS_PER_S) % period;
 	const dist = Math.abs(index + CLASSIC_PADDING - pos);
 	if (dist >= CLASSIC_BAND_HALF_WIDTH) return 0;
 	return 0.5 * (1 + Math.cos((Math.PI * dist) / CLASSIC_BAND_HALF_WIDTH));
@@ -119,9 +126,13 @@ function classicIntensity(time: number, index: number, length: number): number {
 function kittIntensity(time: number, index: number, length: number): number {
 	const range = length - 1;
 	if (range <= 0) return 1;
-	const phase = (time % KITT_CYCLE_MS) / KITT_CYCLE_MS;
-	const goingRight = phase < 0.5;
-	const head = goingRight ? phase * 2 * range : (1 - phase) * 2 * range;
+	// Fixed head velocity: a triangle ping-pong over a 2*range round trip at a
+	// constant cells/second, so the bright head advances ≤1 cell per frame at the
+	// default cadence regardless of bar length. Round-trip duration scales with length.
+	const cycleCells = 2 * range;
+	const sweep = ((time / 1000) * SHIMMER_SPEED_CELLS_PER_S) % cycleCells;
+	const goingRight = sweep < range;
+	const head = goingRight ? sweep : cycleCells - sweep;
 	const delta = index - head;
 	const abs = delta < 0 ? -delta : delta;
 	if (abs <= KITT_HEAD_HALF) return 1;

package/src/modes/theme/theme-schema.json

@@ -406,7 +406,7 @@
 					}
 				},
 				"spinnerFrames": {
-					"description": "Override the spinner frames. Use a flat array to set both `status` and `activity`, or an object to override each independently. Frames are advanced ~12.5fps for status spinners and ~60fps for activity spinners.",
+					"description": "Override the spinner frames. Use a flat array to set both `status` and `activity`, or an object to override each independently. Frames are advanced ~12.5fps for status spinners and ~30fps for activity spinners.",
 					"oneOf": [
 						{
 							"type": "array",