@underactive/pi-topping 0.8.1 → 0.9.0

package/README.md

@@ -6,7 +6,7 @@ We garnish our pies. It seemed rude not to extend Pi the same courtesy. This is
 
 ![Example of pi-topping's decorated user prompt](https://raw.githubusercontent.com/underactive/pi-topping/main/media/demo_user_prompt.png)
 
-**“Working” Loader** — animated spinner (with color choice), randomized activity word, optional word packs, shimmer, token activity monitor, elapsed timer, output token display, live output-token rate, and the response model when it meaningfully differs from the selected model — all arrangeable left to right. During a blocking extension prompt, the loader switches to a stable dim waiting line with a pulsing indicator, then resumes afterward.
+**“Working” Loader** — animated spinner (with color choice), randomized activity word, optional word packs, shimmer, token activity monitor with an adjustable full-scale rate, elapsed timer, output token display, live output-token rate, and the response model when it meaningfully differs from the selected model — all arrangeable left to right. During a blocking extension prompt, the loader switches to a stable dim waiting line with a pulsing indicator, then resumes afterward.
 
 ![Demo of pi-topping's shimmering activity word, scrolling activity meter, elapsed timer, token count, and token rate](https://raw.githubusercontent.com/underactive/pi-topping/main/media/demo.gif)
 
@@ -58,6 +58,7 @@ Run `/topping-settings` (TUI only) to customize your toppings. Settings persist
 ║    [■] Token activity monitor color             ‹ accent ›    ║
 ║    [■] Token activity monitor direction  ‹ Right to Left ›    ║
 ║    [■] Token activity monitor dimmed                 OFF      ║
+║    [■] Token activity monitor upper bound       ‹ 80 tps ›    ║
 ║    [■] Elapsed time since prompt                      ON      ║
 ║    [■] Show output tokens                             ON      ║
 ║    [■] Token rate                                     ON      ║
@@ -108,7 +109,7 @@ Run `/topping-settings` (TUI only) to customize your toppings. Settings persist
 ╟───────────────────────────────────────────────────────────────╢
 ║  ↑↓ move  PgUp/PgDn page  ←→ select                           ║
 ║  ␣ toggle  ⏎ apply  esc cancel                                ║
-╚═══════════════════════════════════════════════════════[ 9/56 ]╝
+╚═══════════════════════════════════════════════════════[ 9/57 ]╝
 ```
 
 ### Word packs
@@ -144,6 +145,8 @@ full brightness for 1.5 seconds, then fades through five theme-aware shades to t
 the next 0.25 seconds before returning to the placeholder; a new count restores full brightness and
 restarts the cycle.
 
+The token activity monitor reaches full `⣿` at or above its configurable upper bound (80 tps by default), with lower levels scaled proportionally to that bound. In `/topping-settings`, `←`/`→` cycle through presets spanning 10–1000 tps, and `␣` (Space) lets you enter any whole number from 10–1000. Invalid typed entries show an inline error and keep the editor open without changing the current value; invalid hand-edited `meterUpperBoundTps` values in `settings.json` revert to 80 on load.
+
 The response model is captured from assistant responses, displayed as its sanitized value with no label only when it meaningfully differs from the selected model, and defaults to the final loader detail after output tokens. While pi-topping-statusline embeds the loader in its status bar, the model slides out tail first from behind its separator over 0.3 seconds when it first appears in a run, like that bar's embedded status; elsewhere it appears at once, and a different model replacing it always swaps in place. Equivalent local paths and decorated filenames are suppressed. Its loader display can be hidden, recolored, permanently dimmed, or reordered. The independent **Response model footer** option is disabled by default; when enabled, the final model appears under the editor after settlement, remains visible for 3 seconds, fades through five theme-aware shades over 0.5 seconds, then clears. New work cancels the pending fade. When the active provider is `switchyard`, the loader and footer hold/fade use NVIDIA green (`#84c51a`, matching pi-topping-statusline) regardless of the configured Response model color; the dim setting still applies.
 
 ## Requirements
@@ -160,7 +163,7 @@ npm test
 npm run typecheck
 ```
 
-Tests cover the word/shimmer rendering, prompt box and completion marker rendering, activity meter behavior, timer resets, settings persistence and schema migrations, word-pack parsing, loading, and default-text selection, response-model loader and footer behavior, the `menu.ts` component, the settings menu wiring end to end, and the `/topping-setup` command's install and uninstall flows.
+Tests cover the word/shimmer rendering, prompt box and completion marker rendering, activity meter behavior and its configurable upper bound, timer resets, settings persistence and schema migrations, word-pack parsing, loading, and default-text selection, response-model loader and footer behavior, the `menu.ts` component and its typed number entry, the settings menu wiring end to end, and the `/topping-setup` command's install and uninstall flows.
 
 ## Limitations
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@underactive/pi-topping",
-  "version": "0.8.1",
+  "version": "0.9.0",
   "description": "A Pi extension that adds quality of life improvements to Pi's UX: a high-vis user prompt, a shimmering working loader with token activity meter and elapsed timer, and an end-of-turn completion marker",
   "keywords": ["pi-package", "pi-extension"],
   "license": "MIT",
@@ -30,8 +30,8 @@
     "@earendil-works/pi-tui": "*"
   },
   "devDependencies": {
-    "@earendil-works/pi-coding-agent": "0.86.0",
-    "@earendil-works/pi-tui": "0.86.0",
+    "@earendil-works/pi-coding-agent": "0.99.1",
+    "@earendil-works/pi-tui": "0.99.1",
     "@types/node": "^24.0.0",
     "typescript": "^5.9.3"
   },

package/src/activity-meter.ts

@@ -15,6 +15,9 @@ export const ActivityMeterLevel = {
 export type ActivityMeterLevel = (typeof ActivityMeterLevel)[keyof typeof ActivityMeterLevel];
 
 const EMA_ALPHA = 0.4;
+export const DEFAULT_METER_UPPER_BOUND_TPS = 80;
+export const METER_UPPER_BOUND_TPS_MIN = 10;
+export const METER_UPPER_BOUND_TPS_MAX = 1000;
 const BRAILLE: Record<ActivityMeterLevel, string> = {
 	[ActivityMeterLevel.IDLE]: "⢀",
 	[ActivityMeterLevel.LOW]: "⣀",
@@ -26,13 +29,19 @@ const BRAILLE: Record<ActivityMeterLevel, string> = {
 	[ActivityMeterLevel.FULL]: "⣿",
 };
 const WIDTH = 8;
-const RATE_THRESHOLDS = [0, 5, 10, 15, 22, 30, 40] as const;
+const LEGACY_FULL_SCALE_TPS = 40;
+// Levels below full retain the original 40 tps scale's proportions.
+const RATE_THRESHOLDS = [0, 5, 10, 15, 22, 30] as const;
 type CellColorizer = (level: ActivityMeterLevel, char: string) => string;
 
-/** Convert an estimated output-token rate to a display level. */
-export function rateToLevel(tokensPerSecond: number): ActivityMeterLevel {
+/**
+ * Convert an estimated output-token rate to a display level. Rates at or above `upperBoundTps`
+ * render as full; the lower levels scale in proportion to the bound.
+ */
+export function rateToLevel(tokensPerSecond: number, upperBoundTps: number = DEFAULT_METER_UPPER_BOUND_TPS): ActivityMeterLevel {
+	if (tokensPerSecond >= upperBoundTps) return ActivityMeterLevel.FULL;
 	for (let i = RATE_THRESHOLDS.length - 1; i >= 0; i--) {
-		if (tokensPerSecond > RATE_THRESHOLDS[i]) return (i + 1) as ActivityMeterLevel;
+		if (tokensPerSecond * LEGACY_FULL_SCALE_TPS > RATE_THRESHOLDS[i]! * upperBoundTps) return (i + 1) as ActivityMeterLevel;
 	}
 	return ActivityMeterLevel.IDLE;
 }

package/src/menu.ts

@@ -4,7 +4,7 @@
  * contract and `ctx.ui.custom()` overlay API.
  *
  * Renders a titled box containing one or more sections of boolean toggle,
- * multi-value cycle, or keyboard-reorderable items, plus an optional live-updating
+ * multi-value cycle (including optional typed whole-number entry), or keyboard-reorderable items, plus an optional live-updating
  * preview section driven by a caller-supplied render callback.
  *
  * Intended to be reused by any extension that needs a simple modal toggle
@@ -12,10 +12,16 @@
  */
 
 import type { ExtensionCommandContext, Theme } from "@earendil-works/pi-coding-agent";
-import { type Component, Key, matchesKey, truncateToWidth, type SizeValue, type TUI, visibleWidth } from "@earendil-works/pi-tui";
+import { type Component, decodeKittyPrintable, Key, matchesKey, truncateToWidth, type SizeValue, type TUI, visibleWidth } from "@earendil-works/pi-tui";
 
 export type MenuValue = boolean | string;
 
+export interface MenuNumberEntry {
+	min: number;
+	max: number;
+	unit?: string;
+}
+
 /** Lines to display and an optional delay before the preview should refresh. */
 export interface PreviewResult {
 	lines: string[];
@@ -40,6 +46,8 @@ export interface MenuItem {
 	cycleEnabled?: boolean;
 	/** Value snapped to when the gating checkbox is unchecked. */
 	cycleDisabledValue?: string;
+	/** Also accept a typed whole number in [min, max]; space opens the editor. Values publish as decimal strings. */
+	numberEntry?: MenuNumberEntry;
 	/**
 	 * Marks the item as a reorderable row. Space grabs/releases it; while grabbed,
 	 * up/down move it among the other rows sharing this group instead of moving the
@@ -81,6 +89,8 @@ export interface MenuResult<T> {
 }
 
 const DEFAULT_HINTS = ["\u2191\u2193 move", "PgUp/PgDn page", "\u2423 toggle", "\u23ce apply", "esc cancel"];
+const EDIT_HINTS = ["type a whole number", "⌫ delete", "⏎ confirm", "esc cancel edit"];
+const MAX_EDIT_CHARS = 8;
 const OVERLAY_WIDTH = "86%";
 export const DEFAULT_PREVIEW_WIDTH = 76;
 const ROW_PREFIX_WIDTH = 8; // "  " + marker + " " + "[" + box + "]" + " "
@@ -97,6 +107,13 @@ interface FlatItem {
 	sectionIndex: number;
 }
 
+function parseWholeNumber(raw: string, spec: MenuNumberEntry): number | undefined {
+	const trimmed = raw.trim();
+	if (!/^\d+$/.test(trimmed)) return undefined;
+	const value = Number(trimmed);
+	return value >= spec.min && value <= spec.max ? value : undefined;
+}
+
 function buildInitialValues(config: MenuConfig): Record<string, MenuValue> {
 	const values: Record<string, MenuValue> = {};
 	const reorderGroups = new Map<string, string[]>();
@@ -139,6 +156,7 @@ export class MenuComponent implements Component {
 	private cachedRows: number | undefined;
 	private cachedLines: string[] | undefined;
 	private pageItemCount: number | undefined;
+	private editing: { buffer: string; invalid: boolean } | undefined;
 
 	constructor(
 		config: MenuConfig,
@@ -191,6 +209,10 @@ export class MenuComponent implements Component {
 			}
 			return;
 		}
+		if (this.editing) {
+			this.handleEditInput(data);
+			return;
+		}
 
 		// Map input to a normalized key name.
 		let mappedKey: string | undefined;
@@ -220,6 +242,11 @@ export class MenuComponent implements Component {
 			[Key.space]: () => {
 				const item = this.flat[this.cursor]!.item;
 				if (this.isDisabled(item)) return;
+				if (item.numberEntry) {
+					this.editing = { buffer: "", invalid: false };
+					this.invalidate();
+					return;
+				}
 				if (item.cycleValues && item.cycleEnabledBy) {
 					this.values[item.cycleEnabledBy] = !this.values[item.cycleEnabledBy] as boolean;
 					if (!this.values[item.cycleEnabledBy] && item.cycleDisabledValue !== undefined) this.values[item.id] = item.cycleDisabledValue;
@@ -251,6 +278,32 @@ export class MenuComponent implements Component {
 		return lines;
 	}
 
+	private handleEditInput(data: string): void {
+		const editing = this.editing!;
+		const item = this.flat[this.cursor]!.item;
+		const spec = item.numberEntry!;
+		if (matchesKey(data, Key.enter)) {
+			const value = parseWholeNumber(editing.buffer, spec);
+			if (value === undefined) editing.invalid = true;
+			else {
+				this.values[item.id] = String(value);
+				this.editing = undefined;
+			}
+		} else if (matchesKey(data, Key.escape) || matchesKey(data, Key.ctrl("c"))) {
+			this.editing = undefined;
+		} else if (matchesKey(data, Key.backspace)) {
+			editing.buffer = [...editing.buffer].slice(0, -1).join("");
+			editing.invalid = false;
+		} else {
+			const text = decodeKittyPrintable(data) ?? data;
+			if (/^[\x20-\x7e]+$/.test(text) && editing.buffer.length + text.length <= MAX_EDIT_CHARS) {
+				editing.buffer += text;
+				editing.invalid = false;
+			}
+		}
+		this.invalidate();
+	}
+
 	/**
 	 * Move the grabbed reorder row within its group, clamped at the group edges.
 	 * Returns true when the key belongs to the mover and must not also move the
@@ -299,7 +352,29 @@ export class MenuComponent implements Component {
 	private cycleCurrentValue(delta: number): void {
 		const item = this.flat[this.cursor]!.item;
 		if (this.isDisabled(item) || !item.cycleValues?.length || (item.cycleEnabledBy && !this.values[item.cycleEnabledBy])) return;
-		const current = item.cycleValues.indexOf(this.values[item.id] as string);
+		const currentValue = this.values[item.id] as string;
+		const current = item.cycleValues.indexOf(currentValue);
+		if (item.numberEntry && current === -1) {
+			const numericCurrent = Number(currentValue);
+			if (delta > 0) {
+				for (const preset of item.cycleValues) {
+					if (Number(preset) > numericCurrent) {
+						this.values[item.id] = preset;
+						this.invalidate();
+						return;
+					}
+				}
+			} else {
+				for (let i = item.cycleValues.length - 1; i >= 0; i--) {
+					const preset = item.cycleValues[i]!;
+					if (Number(preset) < numericCurrent) {
+						this.values[item.id] = preset;
+						this.invalidate();
+						return;
+					}
+				}
+			}
+		}
 		const index = (current + delta + item.cycleValues.length) % item.cycleValues.length;
 		this.values[item.id] = item.cycleValues[index]!;
 		this.invalidate();
@@ -529,6 +604,13 @@ export class MenuComponent implements Component {
 	}
 
 	private renderHintsRow(innerWidth: number): string {
+		if (this.editing) {
+			const item = this.flat[this.cursor]!.item;
+			const spec = item.numberEntry!;
+			const unit = spec.unit ? ` ${spec.unit}` : "";
+			const error = this.editing.invalid ? `${this.theme.fg("error", `✗ Enter a whole number from ${spec.min} to ${spec.max}${unit}`)}  ` : "";
+			return this.renderContentRow(`  ${error}${this.theme.fg("dim", EDIT_HINTS.join("  "))}`, innerWidth);
+		}
 		const plain = `  ${this.hints.join("  ")}`;
 		return this.renderContentRow(this.theme.fg("dim", plain), innerWidth);
 	}
@@ -559,13 +641,17 @@ export class MenuComponent implements Component {
 		if (item.cycleValues) {
 			const enabled = !this.isDisabled(item) && (item.cycleEnabledBy ? this.values[item.cycleEnabledBy] as boolean : true);
 			const rawValue = typeof value === "string" ? value : String(value);
-			const displayValue = item.cycleValueLabels?.[rawValue] ?? rawValue;
-			const stateWord = `‹ ${displayValue} ›`;
-			const maxLabelLen = Math.max(0, innerWidth - ROW_PREFIX_WIDTH - visibleWidth(stateWord) - 1);
+			const unit = item.numberEntry?.unit ? ` ${item.numberEntry.unit}` : "";
+			const displayValue = item.numberEntry ? `${rawValue}${unit}` : item.cycleValueLabels?.[rawValue] ?? rawValue;
+			const editing = selected ? this.editing : undefined;
+			const stateWord = editing ? `‹ ${editing.buffer}▌${unit} ›` : `‹ ${displayValue} ›`;
+			const rightPlain = `${stateWord}  `;
+			const maxLabelLen = Math.max(0, innerWidth - ROW_PREFIX_WIDTH - visibleWidth(rightPlain) - 1);
 			const label = visibleWidth(item.label) > maxLabelLen ? truncateToWidth(item.label, maxLabelLen) : item.label;
 			const leftPlain = `  ${marker} [${enabled ? "■" : " "}] ${label}`;
 			const gap = Math.max(1, innerWidth - visibleWidth(leftPlain) - visibleWidth(stateWord) - 2);
-			const content = `  ${markerColored} [${enabled ? th.fg("success", "■") : th.fg("muted", " ")}] ${th.fg("text", label)}${" ".repeat(gap)}${enabled ? th.fg("accent", stateWord) : th.fg("muted", stateWord)}  `;
+			const state = editing ? th.fg(editing.invalid ? "error" : "accent", stateWord) : enabled ? th.fg("accent", stateWord) : th.fg("muted", stateWord);
+			const content = `  ${markerColored} [${enabled ? th.fg("success", "■") : th.fg("muted", " ")}] ${th.fg("text", label)}${" ".repeat(gap)}${state}  `;
 			return this.wrap("\u2551", selected ? th.bg("selectedBg", content) : content, "\u2551");
 		}
 

package/src/preview.ts

@@ -1,11 +1,11 @@
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { DEFAULT_PREVIEW_WIDTH, type PreviewResult } from "./menu.ts";
-import { ActivityMeter, rateToLevel } from "./activity-meter.ts";
+import { ActivityMeter, METER_UPPER_BOUND_TPS_MAX, METER_UPPER_BOUND_TPS_MIN, rateToLevel } from "./activity-meter.ts";
 import { DEFAULT_WORKING_WORD, dimAttribute, ELAPSED_INTERVAL_MS, formatTokenRate, getThinkingLevelColorizer, METER_INTERVAL_MS, SHIMMER_INTERVAL_MS, SPINNER_FRAME_MS } from "./format.ts";
 import { buildLoaderMessage } from "./loader-message.ts";
 import { getResponseModelColorizer } from "./nvidia-green.ts";
 import { buildCompletionMarkerContent, buildCompletionMarkerLine, buildPromptBoxLines } from "./prompt-decorator.ts";
-import { DEFAULT_SETTINGS, fromCycleDirection, fromCycleSpeed, isBorderStyle, isDoneMarkerBorderColor, isDoneMarkerBorderStyle, isDoneMarkerStyle, isPromptBorderColor, isSpinnerColor, isThinkingLevelColor, LOADER_ORDER_ID, MENU_ENTRIES, parseLoaderOrder } from "./settings.ts";
+import { DEFAULT_SETTINGS, fromCycleDirection, fromCycleMeterUpperBound, fromCycleSpeed, isBorderStyle, isDoneMarkerBorderColor, isDoneMarkerBorderStyle, isDoneMarkerStyle, isPromptBorderColor, isSpinnerColor, isThinkingLevelColor, LOADER_ORDER_ID, MENU_ENTRIES, parseLoaderOrder } from "./settings.ts";
 import { isWordPackEnabled, selectWorkingTextSelection, WORD_PACK_MENU_PREFIX, wordPacksPath, type WordPack } from "./word-packs.ts";
 // Simulated load for the menu preview: a 2.4s cosine wave peaking at 46 tps for the meter,
 // flat 28 tps for the token readouts.
@@ -49,12 +49,15 @@ export class PreviewRenderer {
 		} else if (values.elapsedTime !== false || values.outputTokens !== false) {
 			nextRefreshInMs = ELAPSED_INTERVAL_MS;
 		}
-		return { lines: ["", this.loaderPreview(values, elapsedMs), ""], nextRefreshInMs };
+		const help = activeItemId === "meterUpperBoundTps"
+			? this.#ctx.ui.theme.fg("dim", `⣿ at ${fromCycleMeterUpperBound(values.meterUpperBoundTps)} tps or more · ←→ presets · ␣ type ${METER_UPPER_BOUND_TPS_MIN}–${METER_UPPER_BOUND_TPS_MAX}`)
+			: "";
+		return { lines: ["", this.loaderPreview(values, elapsedMs), help], nextRefreshInMs };
 	}
 	private loaderPreview(values: Record<string, boolean | string>, elapsedMs: number): string {
 		this.#meter.setDirection(fromCycleDirection(values.meterDirection));
 		if (elapsedMs - this.#lastMeterUpdate >= METER_INTERVAL_MS) {
-			this.#meter.push(rateToLevel(meterRate(elapsedMs)));
+			this.#meter.push(rateToLevel(meterRate(elapsedMs), fromCycleMeterUpperBound(values.meterUpperBoundTps)));
 			this.#lastMeterUpdate = elapsedMs;
 		}
 		const features = { substituteDefaultMessage: values.substituteDefaultMessage !== false, elapsedTime: values.elapsedTime !== false, outputTokens: values.outputTokens !== false, tokenRate: values.showTokenRate !== false, responseModel: values.showResponseModel !== false };

package/src/session.ts

@@ -632,7 +632,7 @@ export class SessionManager {
 			hasNewTokenCount = total > state.lastTokenRateTotal;
 			state.lastTokenRateTotal = total;
 			const tokenRate = state.rateTracker.sample(total, now);
-			if (decorations.tokenActivityMonitor) state.activityMeter.push(rateToLevel(tokenRate));
+			if (decorations.tokenActivityMonitor) state.activityMeter.push(rateToLevel(tokenRate, decorations.meterUpperBoundTps));
 			state.lastTokenRateSampledAt = now;
 		}
 		const responseModelShown = features.responseModel && state.responseModel

package/src/settings.ts

@@ -1,8 +1,9 @@
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import { mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
+import { DEFAULT_METER_UPPER_BOUND_TPS, METER_UPPER_BOUND_TPS_MAX, METER_UPPER_BOUND_TPS_MIN } from "./activity-meter.ts";
 import { DEFAULT_LOADER_ORDER, type LoaderElement } from "./format.ts";
-import type { MenuSection } from "./menu.ts";
+import type { MenuNumberEntry, MenuSection } from "./menu.ts";
 import { isWordPackEnabled, isWordPackId, WORD_PACK_MENU_PREFIX, type WordPack } from "./word-packs.ts";
 import { isPlainObject } from "./util.ts";
 
@@ -29,6 +30,7 @@ export const DONE_MARKER_BORDER_STYLE_VALUES = [...BORDER_STYLE_VALUES, "none"]
 export type DoneMarkerBorderStyle = (typeof DONE_MARKER_BORDER_STYLE_VALUES)[number];
 export const DONE_MARKER_STYLE_VALUES = ["elite", "bookend"] as const;
 export type DoneMarkerStyle = (typeof DONE_MARKER_STYLE_VALUES)[number];
+export const METER_UPPER_BOUND_TPS_PRESETS = ["10", "20", "30", "40", "50", "60", "80", "100", "150", "200", "300", "500", "1000"] as const;
 
 export function isBorderStyle(value: unknown): value is BorderStyle {
 	return typeof value === "string" && BORDER_STYLE_VALUES.some(style => style === value);
@@ -54,6 +56,19 @@ export const isSpinnerColor = isThinkingLevelSettingColor;
 export const isPromptBorderColor = isThinkingLevelSettingColor;
 export const isDoneMarkerBorderColor = isThinkingLevelSettingColor;
 
+export function parseMeterUpperBoundTps(value: unknown): number | undefined {
+	if (typeof value === "number") {
+		return Number.isInteger(value) && value >= METER_UPPER_BOUND_TPS_MIN && value <= METER_UPPER_BOUND_TPS_MAX ? value : undefined;
+	}
+	if (typeof value !== "string" || !/^\s*\d+\s*$/.test(value)) return undefined;
+	const parsed = Number(value);
+	return parsed >= METER_UPPER_BOUND_TPS_MIN && parsed <= METER_UPPER_BOUND_TPS_MAX ? parsed : undefined;
+}
+
+export function fromCycleMeterUpperBound(value: unknown): number {
+	return parseMeterUpperBoundTps(value) ?? DEFAULT_METER_UPPER_BOUND_TPS;
+}
+
 export interface DecoratorSettings {
 	decorations: {
 		animatedSpinner: boolean;
@@ -81,6 +96,7 @@ export interface DecoratorSettings {
 		meterColor: ThinkingLevelColor;
 		meterColorEnabled: boolean;
 		meterDimmed: boolean;
+		meterUpperBoundTps: number;
 		tokenRateColor: ThinkingLevelColor;
 		tokenRateDimmed: boolean;
 		responseModelColor: ThinkingLevelColor;
@@ -111,7 +127,7 @@ export interface DecoratorSettings {
 }
 
 export const DEFAULT_SETTINGS: DecoratorSettings = {
-	decorations: { animatedSpinner: true, shimmer: true, shimmerInverted: false, shimmerDirection: "ltr", shimmerDirectionEnabled: true, shimmerSpeed: "normal", shimmerSpeedEnabled: true, tokenActivityMonitor: true, meterDirection: "rtl", meterDirectionEnabled: true, decorateUserPrompt: true, borderColor: "thinking-level", borderColorEnabled: true, borderStyle: "double", borderStyleEnabled: true, doneMarkerBorderStyle: "none", doneMarkerBorderColor: "thinking-level", doneMarkerStyle: "elite", doneMarkerModelColor: "muted", doneMarkerModelDimmed: false, spinnerColor: "thinking-level", spinnerColorEnabled: true, meterColor: "accent", meterColorEnabled: true, meterDimmed: false, tokenRateColor: "warning", tokenRateDimmed: false, responseModelColor: "accent", responseModelDimmed: false, promptIcon: true, promptTimestamp: true, promptProvider: true, promptModel: true, useNerdFont: true },
+	decorations: { animatedSpinner: true, shimmer: true, shimmerInverted: false, shimmerDirection: "ltr", shimmerDirectionEnabled: true, shimmerSpeed: "normal", shimmerSpeedEnabled: true, tokenActivityMonitor: true, meterDirection: "rtl", meterDirectionEnabled: true, decorateUserPrompt: true, borderColor: "thinking-level", borderColorEnabled: true, borderStyle: "double", borderStyleEnabled: true, doneMarkerBorderStyle: "none", doneMarkerBorderColor: "thinking-level", doneMarkerStyle: "elite", doneMarkerModelColor: "muted", doneMarkerModelDimmed: false, spinnerColor: "thinking-level", spinnerColorEnabled: true, meterColor: "accent", meterColorEnabled: true, meterDimmed: false, meterUpperBoundTps: DEFAULT_METER_UPPER_BOUND_TPS, tokenRateColor: "warning", tokenRateDimmed: false, responseModelColor: "accent", responseModelDimmed: false, promptIcon: true, promptTimestamp: true, promptProvider: true, promptModel: true, useNerdFont: true },
 	features: { substituteDefaultMessage: true, elapsedTime: true, outputTokens: true, tokenRate: true, responseModel: true, responseModelFooter: false, doneMarker: true, doneMarkerIcon: true, randomizeDoneMarker: true, doneMarkerTokens: true, doneMarkerInputs: true, doneMarkerModel: true, includeDefaultWorkingText: true },
 	loaderOrder: [...DEFAULT_LOADER_ORDER],
 	wordPacks: {},
@@ -146,12 +162,12 @@ export function parseLoaderOrder(value: unknown): LoaderElement[] {
 }
 
 export function settingsPath(): string { return join(getAgentDir(), "pi-topping", "settings.json"); }
-function mergeGroup<T extends Record<string, boolean | string>>(defaults: T, parsed: unknown): T {
+function mergeGroup<T extends Record<string, boolean | string | number>>(defaults: T, parsed: unknown): T {
 	const merged = { ...defaults };
 	if (!isPlainObject(parsed)) return merged;
 	for (const [key, value] of Object.entries(parsed)) {
 		if (!Object.hasOwn(merged, key)) continue;
-		if (typeof merged[key] === "boolean" && typeof value === "boolean") (merged as Record<string, boolean | string>)[key] = value;
+		if (typeof merged[key] === "boolean" && typeof value === "boolean") (merged as Record<string, boolean | string | number>)[key] = value;
 	}
 	return merged;
 }
@@ -171,8 +187,8 @@ type DecorationSettings = DecoratorSettings["decorations"];
 type FeatureSettings = DecoratorSettings["features"];
 type DecorationBooleanKey = { [Key in keyof DecorationSettings]: DecorationSettings[Key] extends boolean ? Key : never }[keyof DecorationSettings];
 type MenuEntryBase = { id: string; label: string; section: MenuSectionName };
-type DecorationMenuEntry = MenuEntryBase & { group: "decorations"; key: keyof DecorationSettings; cycleValues?: readonly string[]; cycleValueLabels?: Readonly<Record<string, string>>; cycleEnabledBy?: DecorationBooleanKey; cycleDisabledValue?: string };
-type FeatureMenuEntry = MenuEntryBase & { group: "features"; key: keyof FeatureSettings; cycleValues?: never; cycleValueLabels?: never; cycleEnabledBy?: never; cycleDisabledValue?: never };
+type DecorationMenuEntry = MenuEntryBase & { group: "decorations"; key: keyof DecorationSettings; cycleValues?: readonly string[]; cycleValueLabels?: Readonly<Record<string, string>>; cycleEnabledBy?: DecorationBooleanKey; cycleDisabledValue?: string; numberEntry?: MenuNumberEntry };
+type FeatureMenuEntry = MenuEntryBase & { group: "features"; key: keyof FeatureSettings; cycleValues?: never; cycleValueLabels?: never; cycleEnabledBy?: never; cycleDisabledValue?: never; numberEntry?: never };
 type MenuEntry = DecorationMenuEntry | FeatureMenuEntry;
 const THINKING_LEVEL_CYCLE_LABELS = { "thinking-level": "thinkingLevel" } as const;
 const DIRECTION_CYCLE_LABELS = { ltr: "Left to Right", rtl: "Right to Left" } as const;
@@ -196,6 +212,7 @@ export const MENU_ENTRIES: readonly MenuEntry[] = [
 	{ id: "meterColor", label: "Token activity monitor color", section: "“Working” Loader", group: "decorations", key: "meterColor", cycleValues: THINKING_LEVEL_COLOR_VALUES, cycleValueLabels: THINKING_LEVEL_CYCLE_LABELS, cycleEnabledBy: "meterColorEnabled", cycleDisabledValue: "accent" },
 	{ id: "meterDirection", label: "Token activity monitor direction", section: "“Working” Loader", group: "decorations", key: "meterDirection", cycleValues: ["ltr", "rtl"], cycleValueLabels: DIRECTION_CYCLE_LABELS, cycleEnabledBy: "meterDirectionEnabled", cycleDisabledValue: "rtl" },
 	{ id: "meterDimmed", label: "Token activity monitor dimmed", section: "“Working” Loader", group: "decorations", key: "meterDimmed" },
+	{ id: "meterUpperBoundTps", label: "Token activity monitor upper bound", section: "“Working” Loader", group: "decorations", key: "meterUpperBoundTps", cycleValues: METER_UPPER_BOUND_TPS_PRESETS, numberEntry: { min: METER_UPPER_BOUND_TPS_MIN, max: METER_UPPER_BOUND_TPS_MAX, unit: "tps" } },
 	{ id: "elapsedTime", label: "Elapsed time since prompt", section: "“Working” Loader", group: "features", key: "elapsedTime" },
 	{ id: "outputTokens", label: "Show output tokens", section: "“Working” Loader", group: "features", key: "outputTokens" },
 	// id differs from key: the Elements Order row already owns "tokenRate" in the menu's shared value namespace.
@@ -227,7 +244,7 @@ function menuItem(entry: MenuEntry, settings: DecoratorSettings): MenuSection["i
 	const cycleEnabled = entry.group === "decorations" && entry.cycleEnabledBy
 		? settings.decorations[entry.cycleEnabledBy]
 		: undefined;
-	return { id: entry.id, label: entry.label, cycleValues: entry.cycleValues, cycleValueLabels: entry.cycleValueLabels, cycleEnabledBy: entry.cycleEnabledBy, cycleDisabledValue: entry.cycleDisabledValue, cycleEnabled, value };
+	return { id: entry.id, label: entry.label, cycleValues: entry.cycleValues, cycleValueLabels: entry.cycleValueLabels, cycleEnabledBy: entry.cycleEnabledBy, cycleDisabledValue: entry.cycleDisabledValue, cycleEnabled, numberEntry: entry.numberEntry, value: typeof value === "number" ? String(value) : value };
 }
 
 function isDecorationBooleanKey(key: keyof DecorationSettings): key is DecorationBooleanKey {
@@ -263,6 +280,11 @@ function setDecorationCycleValue(decorations: DecorationSettings, key: keyof Dec
 		case "shimmerSpeed":
 			if (value === "slow" || value === "normal" || value === "fast") decorations[key] = value;
 			return;
+		case "meterUpperBoundTps": {
+			const bound = parseMeterUpperBoundTps(value);
+			if (bound !== undefined) decorations[key] = bound;
+			return;
+		}
 		default:
 			// Fail loudly if a MENU_ENTRIES cycle entry is added without a handler here.
 			throw new Error(`Unhandled cycle setting: ${String(key)}`);
@@ -298,7 +320,7 @@ export function applyMenuResult(settings: DecoratorSettings, values: Record<stri
 	for (const entry of MENU_ENTRIES) {
 		const value = values[entry.id];
 		if (value === undefined) continue;
-		if (entry.group === "decorations" && entry.cycleValues && typeof value === "string" && entry.cycleValues.includes(value)) {
+		if (entry.group === "decorations" && entry.cycleValues && typeof value === "string" && (entry.cycleValues.includes(value) || entry.numberEntry !== undefined)) {
 			setDecorationCycleValue(next.decorations, entry.key, value);
 			if (entry.cycleEnabledBy) next.decorations[entry.cycleEnabledBy] = values[entry.cycleEnabledBy] !== false;
 		} else if (entry.group === "decorations" && typeof value === "boolean" && isDecorationBooleanKey(entry.key)) {
@@ -324,7 +346,8 @@ export function applyMenuResult(settings: DecoratorSettings, values: Record<stri
  * Files with `schemaVersion` below 2 get spinner color reset to `thinking-level` and
  * `borderAccent` prompt borders moved to `thinking-level`; below 3, the completion-marker
  * border color is reset. Below 4, the response-model footer inherits the response-model
- * setting. A legacy `features.simCityWorkingText: true` enables the
+ * setting. A missing, non-integer, or out-of-range meter upper bound resolves
+ * to the default of 80 tps. A legacy `features.simCityWorkingText: true` enables the
  * `simcity` pack when no explicit preference is stored.
  */
 export function loadSettings(): DecoratorSettings {
@@ -349,6 +372,8 @@ export function loadSettings(): DecoratorSettings {
 				setDecorationCycleValue(settings.decorations, k,
 					value === "default" && (k === "spinnerColor" || k === "doneMarkerBorderColor") ? "thinking-level" : value);
 			}
+			const bound = parseMeterUpperBoundTps(parsed.decorations.meterUpperBoundTps);
+			if (bound !== undefined) settings.decorations.meterUpperBoundTps = bound;
 		}
 		const schemaVersion = typeof parsed.schemaVersion === "number" ? parsed.schemaVersion : 1;
 		if (schemaVersion < THINKING_LEVEL_COLOR_MIGRATION_VERSION) {