@underactive/pi-topping 0.5.1 → 0.6.0

package/README.md

@@ -6,11 +6,11 @@ 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, shimmer (with direction, speed, and invert option), token activity monitor (with color, direction, and dim toggle), elapsed timer, output token display, and live output-token rate (with color choice and dim toggle) — all arrangeable left to right.
+**“Working” Loader** — animated spinner (with color choice), randomized activity word, optional word packs, shimmer (with direction, speed, and invert option), token activity monitor (with color, direction, and dim toggle), elapsed timer, output token display, and live output-token rate (with color choice and dim toggle) — all arrangeable left to right.
 
 ![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)
 
-**Completion Marker** — end-of-turn marker with icon, randomized verb, token consumption display, and optional border-style/color decorations. Border style defaults to `none`; `heavy` renders e.g. `┗━━ π Mustered for 4s (↓ 25 tokens) ━━━━━━ ━━━━ ━━ ━`. If you steered or followed up (`Alt+Enter`) while Pi was working, the marker also tallies those, e.g. `π Whisked for 2s (↓ 55 tokens · 2 mid-turn inputs)`. Hooks into Pi's `agent_settled` event.
+**Completion Marker** — end-of-turn marker with icon, randomized verb (or `Worked`; matching past tense when Randomize "Worked" text is on), token consumption display, and optional marker-style, border-style, and border-color decorations spanning the full terminal width. The default `elite` style trails the summary with tapering dashes; `bookend` fills the remaining width to a closing corner glyph. Hooks into Pi's `agent_settled` event.
 
 ![Example of pi-topping's completion marker](https://raw.githubusercontent.com/underactive/pi-topping/main/media/demo_completion_marker.png)
 
@@ -23,7 +23,7 @@ Run `/topping-settings` (TUI only) to customize your toppings. Settings persist
 ╔═[ Pi Topping: Settings ]═══════════════════════════════════╗
 ╟─ Preview ──────────────────────────────────────────────────╢
 ║                                                            ║
-║ ⠋ Crafting… ⣠⣤⣶⣶⣤⣠⣀⢀ 28 tok/s · 3s · ↓ 84 tokens           ║
+║ ⠋ Crafting… ⣠⣤⣶⣶⣤⣠⣀⢀ 28 tok/s · 3s · ↓ 84 tokens          ║
 ║                                                            ║
 ╟─ User Prompt ──────────────────────────────────────────────╢
 ║    [■] High-vis prompt                                ON   ║
@@ -62,6 +62,7 @@ Run `/topping-settings` (TUI only) to customize your toppings. Settings persist
 ║                                                            ║
 ╟─ Completion Marker ────────────────────────────────────────╢
 ║    [■] Show completion marker                         ON   ║
+║    [■] Marker style                              ‹ elite › ║
 ║    [■] Border style                               ‹ none › ║
 ║    [■] Border color                       ‹ borderAccent › ║
 ║    [■] Pi icon                                        ON   ║
@@ -69,22 +70,35 @@ Run `/topping-settings` (TUI only) to customize your toppings. Settings persist
 ║    [■] Tokens spent                                   ON   ║
 ║    [■] Mid-turn inputs                                ON   ║
 ║                                                            ║
+╟─ Word Packs ───────────────────────────────────────────────╢
+║    [ ] SimCity                                       OFF   ║
+║    [ ] Star Trek                                     OFF   ║
+║    [ ] Star Wars                                     OFF   ║
+║                                                            ║
 ╟─ Options ──────────────────────────────────────────────────╢
 ║    [■] Use NerdFont icons                             ON   ║
 ╟────────────────────────────────────────────────────────────╢
 ║  ↑↓ move  ←→ select  ␣ toggle  ⏎ apply  esc cancel         ║
-╚════════════════════════════════════════════════════[ 9/37 ]╝
+╚════════════════════════════════════════════════════[ 9/41 ]╝
 ```
 
-❯ marks the keyboard cursor, and the selected row is highlighted. The Provider and Model toggles independently control the lower-right label on decorated prompts.
+### Word packs
 
-The User Prompt Border style cycles through `double`, `single`, `rounded`, and `heavy` box-drawing sets; the Border color row sits directly beneath it. The Completion Marker Border style offers those same choices plus `none`; `none` leaves the marker undecorated, and its Border color row sits directly beneath it.
+Base activity words are always available. All word packs, including the shipped **SimCity**, **Star Trek**, and **Star Wars** packs and custom packs, are disabled by default. Enable packs in `/topping-settings` to add their entries to the same uniformly selected pool. When Randomize “Worked” text is on, the completion marker uses the selected entry’s matching past tense; otherwise it uses `Worked`.
 
-A cycle row's `[■]` box gates it: `␣` unchecks the box, snaps the setting back to its default, and stops `←`/`→` from cycling. The Completion Marker Border style and Border color rows, and Token rate color, have no gate — their box stays `[■]` and `␣` does nothing.
+Bundled packs live in [`wordpacks/`](wordpacks/). Copy `wordpacks/simcity.json`, `wordpacks/star-trek.json`, or `wordpacks/star-wars.json` to `~/.pi/agent/pi-topping/word-packs.json`, then change the pack `id` (the bundled `simcity`, `star-trek`, and `star-wars` IDs are reserved), name, and words:
 
-The User Prompt and Completion Marker Border color settings, along with the Animated spinner, Token activity monitor, and Token rate colors, cycle through `accent`, `border`, `borderAccent`, `success`, `error`, and `warning`.
+```json
+{
+  "packs": [{
+    "id": "cooking",
+    "name": "Cooking",
+    "words": [{ "present_tense": "Sautéing onions", "past_tense": "Sautéed" }]
+  }]
+}
+```
 
-Invert shimmer keeps the working text at the default text color and sweeps a dimmed gradient across it.
+Pack IDs must start with a lowercase letter and contain only lowercase letters, digits, and `-`. Each pack needs a non-empty `name` and at least one word with non-empty `present_tense` and `past_tense` strings. Invalid entries are ignored. Packs reload when a session starts and whenever `/topping-settings` opens, not while a turn is running. Preferences for missing packs are retained so they apply when the pack returns.
 
 Under **Elements Order**, press `␣` to grab a row, then `↑`/`↓` to slide that element
 left or right within the loader. Elapsed time, output tokens, and token rate are joined with

package/index.ts

@@ -1,4 +1,3 @@
-/** pi-topping extension entry point. */
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { SessionManager } from "./src/session.ts";
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@underactive/pi-topping",
-  "version": "0.5.1",
-    "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",
+  "version": "0.6.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",
   "author": "Eric Sison",
@@ -20,7 +20,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "files": ["index.ts", "src/**/*.ts", "README.md", "LICENSE"],
+  "files": ["index.ts", "src/**/*.ts", "wordpacks/*.json", "README.md", "LICENSE"],
   "scripts": {
     "test": "node --test tests/*.test.ts",
     "typecheck": "tsc --noEmit"

package/src/flags.ts

@@ -0,0 +1,19 @@
+/**
+ * Feature gates for unreleased functionality.
+ *
+ * Sibling-topping detection and the `/topping-setup` command ship dark: the
+ * default below stays `false` until the flow is ready for the public. Setting
+ * `PI_TOPPING_SIBLING_SETUP` to any value other than `0`, `false`, `off`, or
+ * `no` (case-insensitive) opts a session in without touching code.
+ */
+
+const SIBLING_SETUP_DEFAULT = false;
+
+const FALSEY_FLAG_VALUES = new Set(["0", "false", "off", "no"]);
+
+/** Whether the sibling-topping setup flow is registered and advertised. */
+export function isSiblingSetupEnabled(): boolean {
+	const value = process.env.PI_TOPPING_SIBLING_SETUP?.trim().toLowerCase();
+	if (value === undefined || value === "") return SIBLING_SETUP_DEFAULT;
+	return !FALSEY_FLAG_VALUES.has(value);
+}

package/src/menu.ts

@@ -1,6 +1,4 @@
 /**
- * menu.ts
- *
  * A reusable, dependency-light box-drawing toggle-menu component for Pi
  * extensions, built on top of `@earendil-works/pi-tui`'s `Component`
  * contract and `ctx.ui.custom()` overlay API.
@@ -74,13 +72,13 @@ export interface MenuConfig {
 	 * since the menu opened. Lines may contain ANSI styling and are truncated/
 	 * padded to fit automatically.
 	 *
-	 * Return `string[]` for legacy interval-based animation (see
-	 * `previewIntervalMs`), or a `PreviewResult` to declare the next refresh.
+	 * Return `string[]` for legacy interval-based animation (defaults to 50ms
+	 * refresh), or a `PreviewResult` to declare the next refresh interval.
 	 * Omitting `nextRefreshInMs` from a `PreviewResult` makes the preview static.
 	 */
-	preview?: (values: Record<string, MenuValue>, elapsedMs: number, activeItemId: string | undefined) => string[] | PreviewResult;
-	/** Fallback delay in ms for legacy `string[]` previews. Default 50. */
-	previewIntervalMs?: number;
+	preview?: (values: Record<string, MenuValue>, elapsedMs: number, activeItemId: string | undefined, width: number) => string[] | PreviewResult;
+	/** Optional heading for the preview block. Defaults to `Preview`. */
+	previewTitle?: string;
 }
 
 export interface MenuResult<T> {
@@ -89,9 +87,17 @@ export interface MenuResult<T> {
 }
 
 const DEFAULT_HINTS = ["\u2191\u2193 move", "\u2423 toggle", "\u23ce apply", "esc cancel"];
-const MAX_WIDTH = 76;
+const OVERLAY_WIDTH = "86%";
+export const DEFAULT_PREVIEW_WIDTH = 76;
 const ROW_PREFIX_WIDTH = 8; // "  " + marker + " " + "[" + box + "]" + " "
 
+/** Close OSC 8 links truncated by pi-tui's SGR-only truncation reset. */
+function closeTruncatedHyperlink(text: string): string {
+	const lastOpen = text.lastIndexOf("\x1b]8;;");
+	const lastClose = text.lastIndexOf("\x1b]8;;\x1b\\");
+	return lastOpen > lastClose ? `${text}\x1b]8;;\x1b\\` : text;
+}
+
 interface FlatItem {
 	id: string;
 	label: string;
@@ -128,11 +134,11 @@ export class MenuComponent implements Component {
 	private readonly title: string;
 	private readonly sections: MenuSection[];
 	private readonly hints: string[];
+	private readonly previewTitle: string;
 	private readonly initialValues: Record<string, MenuValue>;
 	private readonly values: Record<string, MenuValue>;
 	private readonly flat: FlatItem[];
 	private readonly previewFn: MenuConfig["preview"];
-	private readonly previewIntervalMs: number | undefined;
 	private readonly previewOrigin: number | undefined;
 	private readonly tui: TUI | undefined;
 	private previewTimer: ReturnType<typeof setTimeout> | undefined;
@@ -155,6 +161,7 @@ export class MenuComponent implements Component {
 		this.title = config.title;
 		this.sections = config.sections;
 		this.hints = config.hints ?? DEFAULT_HINTS;
+		this.previewTitle = config.previewTitle ?? "Preview";
 		this.tui = tui;
 		this.values = buildInitialValues(config);
 		this.flat = [];
@@ -166,7 +173,6 @@ export class MenuComponent implements Component {
 		this.initialValues = { ...this.values };
 
 		this.previewFn = config.preview;
-		this.previewIntervalMs = config.previewIntervalMs;
 		if (this.previewFn) {
 			this.previewOrigin = Date.now();
 			if (tui) {
@@ -286,16 +292,17 @@ export class MenuComponent implements Component {
 		this.invalidate();
 	}
 
-	private samplePreview(): string[] | undefined {
+	private samplePreview(width: number = DEFAULT_PREVIEW_WIDTH): string[] | undefined {
 		if (!this.previewFn) return undefined;
 
 		const result = this.previewFn(
 			this.values,
 			this.previewOrigin !== undefined ? Date.now() - this.previewOrigin : 0,
 			this.flat[this.cursor]?.id,
+			width,
 		);
 		if (Array.isArray(result)) {
-			this.previewNextRefreshMs = this.previewIntervalMs ?? 50;
+			this.previewNextRefreshMs = 50;
 			return result;
 		}
 
@@ -320,7 +327,7 @@ export class MenuComponent implements Component {
 
 	private buildPreviewBlock(previewLines: string[] | undefined, innerWidth: number): string[] {
 		if (!previewLines?.length) return [];
-		return [this.renderSectionDivider("Preview", innerWidth), this.renderBlankRow(innerWidth), ...previewLines.map(line => this.renderContentRow(` ${line}`, innerWidth)), this.renderBlankRow(innerWidth)];
+		return [this.renderSectionDivider(this.previewTitle, innerWidth), this.renderBlankRow(innerWidth), ...previewLines.map(line => this.renderContentRow(` ${line}`, innerWidth)), this.renderBlankRow(innerWidth)];
 	}
 
 	/** Render every section from `this.flat`, the single source of truth for row order. */
@@ -361,8 +368,7 @@ export class MenuComponent implements Component {
 	}
 
 	/** Render the scrolling settings body while keeping the selected item in view. */
-	private buildResponsiveToggleSections(innerWidth: number, maxRows: number): string[] {
-		const allLines = this.buildToggleSections(innerWidth);
+	private buildResponsiveToggleSections(innerWidth: number, maxRows: number, allLines: string[]): string[] {
 		if (allLines.length <= maxRows) {
 			this.scrollStart = 0;
 			return allLines;
@@ -403,9 +409,10 @@ export class MenuComponent implements Component {
 	}
 
 	private buildLines(maxWidth: number, maxRows?: number): string[] {
-		const previewLines = this.samplePreview();
-		const boxWidth = Math.max(0, Math.min(MAX_WIDTH, maxWidth));
+		const boxWidth = Math.max(0, maxWidth);
 		const innerWidth = Math.max(0, boxWidth - 2);
+		// Preview rows are prefixed with a leading space by buildPreviewBlock/renderContentRow.
+		const previewLines = this.samplePreview(Math.max(0, innerWidth - 1));
 		const header = [this.renderTopBorder(innerWidth), ...this.buildPreviewBlock(previewLines, innerWidth)];
 		const footer = this.buildFooter(innerWidth);
 		const naturalBody = this.buildToggleSections(innerWidth);
@@ -415,7 +422,7 @@ export class MenuComponent implements Component {
 		}
 
 		const bodyRows = Math.max(0, maxRows - header.length - footer.length);
-		const body = this.buildResponsiveToggleSections(innerWidth, bodyRows);
+		const body = this.buildResponsiveToggleSections(innerWidth, bodyRows, naturalBody);
 		return [...header, ...body, ...footer].slice(0, maxRows).map(line => truncateToWidth(line, boxWidth, ""));
 	}
 
@@ -476,7 +483,8 @@ export class MenuComponent implements Component {
 
 	/** Pads/truncates an already-styled content string to exactly `innerWidth` and wraps it in border chars. */
 	private renderContentRow(content: string, innerWidth: number): string {
-		const shown = visibleWidth(content) > innerWidth ? truncateToWidth(content, innerWidth) : content;
+		const truncated = visibleWidth(content) > innerWidth;
+		const shown = truncated ? closeTruncatedHyperlink(truncateToWidth(content, innerWidth)) : content;
 		const pad = Math.max(0, innerWidth - visibleWidth(shown));
 		return this.wrap("\u2551", `${shown}${" ".repeat(pad)}`, "\u2551");
 	}
@@ -553,6 +561,6 @@ export async function showMenu<T extends Record<string, MenuValue>>(
 	return ctx.ui.custom<MenuResult<T>>(
 		(tui, theme, _keybindings, done) =>
 			new MenuComponent(config, theme, done as (result: MenuResult<Record<string, MenuValue>>) => void, tui),
-		{ overlay: true, overlayOptions: { width: MAX_WIDTH, maxHeight: "100%" } },
+		{ overlay: true, overlayOptions: { width: OVERLAY_WIDTH, maxHeight: "100%" } },
 	);
 }

package/src/pi-installer.ts

@@ -0,0 +1,63 @@
+import { spawn } from "node:child_process";
+
+export interface PiInstallResult {
+	code: number;
+	stdout: string;
+	stderr: string;
+}
+
+const SIGKILL_GRACE_MS = 5_000;
+const EXIT_TIMEOUT = 124;
+
+/** Run `pi install <spec>` without relying on Pi's shell-less exec wrapper on Windows. */
+export function spawnPiInstall(spec: string, timeoutMs: number): Promise<PiInstallResult> {
+	if (!/^npm:@?[\w.-]+(\/[\w.-]+)?$/.test(spec)) {
+		return Promise.resolve({ code: 1, stdout: "", stderr: `invalid spec: ${spec}` });
+	}
+	return new Promise((resolve) => {
+		const isWindows = process.platform === "win32";
+		const [command, args, options] = isWindows
+			? (["cmd.exe", ["/c", "pi", "install", spec], { windowsHide: true }] as const)
+			: (["pi", ["install", spec], {}] as const);
+		const processHandle = spawn(command, args, { ...options, stdio: ["ignore", "pipe", "pipe"] });
+		let stdout = "";
+		let stderr = "";
+		let settled = false;
+		let closed = false;
+		let killTimer: ReturnType<typeof setTimeout> | undefined;
+
+		const finish = (result: PiInstallResult): void => {
+			if (settled) return;
+			settled = true;
+			clearTimeout(timeoutTimer);
+			resolve(result);
+		};
+
+		const timeoutTimer = setTimeout(() => {
+			processHandle.kill("SIGTERM");
+			killTimer = setTimeout(() => {
+				if (!closed) processHandle.kill("SIGKILL");
+			}, SIGKILL_GRACE_MS);
+			finish({
+				code: EXIT_TIMEOUT,
+				stdout,
+				stderr: `${stderr}${stderr ? "\n" : ""}[timed out after ${timeoutMs}ms]`,
+			});
+		}, timeoutMs);
+
+		processHandle.stdout?.on("data", (chunk: Buffer) => {
+			stdout += chunk.toString();
+		});
+		processHandle.stderr?.on("data", (chunk: Buffer) => {
+			stderr += chunk.toString();
+		});
+		processHandle.on("error", (error) => {
+			finish({ code: 1, stdout, stderr: `${stderr}${stderr ? "\n" : ""}${error.message}` });
+		});
+		processHandle.on("close", (code) => {
+			closed = true;
+			if (killTimer !== undefined) clearTimeout(killTimer);
+			finish({ code: code ?? 1, stdout, stderr });
+		});
+	});
+}

package/src/preview.ts

@@ -1,28 +1,38 @@
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
-import type { PreviewResult } from "./menu.ts";
+import { DEFAULT_PREVIEW_WIDTH, type PreviewResult } from "./menu.ts";
 import { ActivityMeter, rateToLevel } from "./activity-meter.ts";
 import { buildWorkingMessage, DEFAULT_WORKING_WORD, dimAttribute, ELAPSED_INTERVAL_MS, formatElapsed, formatTokenRate, formatTokens, isFullyDefaultAppearance, METER_INTERVAL_MS, SHIMMER_INTERVAL_MS, shimmerString, SPINNER_FRAME_MS, SPINNER_FRAMES } from "./format.ts";
 import { buildCompletionMarkerContent, buildCompletionMarkerLine, buildPromptBoxLines } from "./prompt-decorator.ts";
-import { DEFAULT_SETTINGS, fromCycleDirection, fromCycleSpeed, isBorderStyle, isDoneMarkerBorderStyle, isSettingColor, LOADER_ORDER_ID, MENU_ENTRIES, parseLoaderOrder } from "./settings.ts";
+import { DEFAULT_SETTINGS, fromCycleDirection, fromCycleSpeed, isBorderStyle, isDoneMarkerBorderStyle, isDoneMarkerStyle, isSettingColor, LOADER_ORDER_ID, MENU_ENTRIES, parseLoaderOrder } from "./settings.ts";
+import { isWordPackEnabled, selectWorkingTextSelection, wordPacksPath, type WordPack } from "./word-packs.ts";
 import { pickRandomWord } from "./words.ts";
 // Simulated load for the menu preview: a 2.4s cosine wave peaking at 46 tok/s for the meter,
 // flat 28 tok/s for the token readouts.
-const METER_PERIOD_MS = 2400, METER_PEAK_RATE = 46, TOKEN_RATE_PER_SEC = 28, PREVIEW_WIDTH = 70;
+const METER_PERIOD_MS = 2400, METER_PEAK_RATE = 46, TOKEN_RATE_PER_SEC = 28;
 const PROMPT_IDS = new Set(MENU_ENTRIES.filter(entry => entry.section === "User Prompt").map(entry => entry.id));
 const MARKER_IDS = new Set(MENU_ENTRIES.filter(entry => entry.section === "Completion Marker").map(entry => entry.id));
 function meterRate(elapsedMs: number): number { return ((1 - Math.cos((2 * Math.PI * elapsedMs) / METER_PERIOD_MS)) / 2) * METER_PEAK_RATE; }
 
 /** Stateful, per-menu preview renderer that follows the active settings section. */
 export class PreviewRenderer {
+	// Preserve constructor-time randomness so rendering never changes the preview phrase.
 	readonly #word = pickRandomWord();
+	readonly #poolFraction = Math.random();
+	readonly #packs: readonly WordPack[];
 	readonly #meter = new ActivityMeter();
 	#lastMeterUpdate = 0;
+	#cachedPackWord = "";
+	#cachedPackSignature = "";
 	readonly #ctx: ExtensionContext;
-	constructor(ctx: ExtensionContext) { this.#ctx = ctx; }
-	render(values: Record<string, boolean | string>, elapsedMs: number, activeItemId?: string): PreviewResult {
-		if (PROMPT_IDS.has(activeItemId ?? "")) return this.promptPreview(values);
-		if (MARKER_IDS.has(activeItemId ?? "")) return this.markerPreview(values);
-		if (activeItemId === "useNerdFont") return { lines: [`Icon preview: ${values.useNerdFont ? "" : "π"}`] };
+	constructor(ctx: ExtensionContext, packs: readonly WordPack[] = []) {
+		this.#ctx = ctx;
+		this.#packs = packs;
+	}
+	render(values: Record<string, boolean | string>, elapsedMs: number, activeItemId?: string, width: number = DEFAULT_PREVIEW_WIDTH): PreviewResult {
+		if (PROMPT_IDS.has(activeItemId ?? "")) return this.promptPreview(values, width);
+		if (MARKER_IDS.has(activeItemId ?? "")) return this.markerPreview(values, width);
+		if (activeItemId === "useNerdFont") return { lines: ["", `Icon preview: ${values.useNerdFont ? "" : "π"}`, ""] };
+		if (activeItemId?.startsWith("pack:")) return this.packPreview(activeItemId.slice("pack:".length), values);
 		let nextRefreshInMs: number | undefined;
 		if (values.shimmer !== false) {
 			nextRefreshInMs = SHIMMER_INTERVAL_MS;
@@ -57,7 +67,14 @@ export class PreviewRenderer {
 		}
 		let word = DEFAULT_WORKING_WORD;
 		if (features.substituteDefaultMessage) {
-			word = this.#word;
+			const packValues = this.packValues(values);
+			const signature = JSON.stringify(Object.keys(packValues).sort().map(k => `${k}=${packValues[k]}`));
+			if (signature !== this.#cachedPackSignature) {
+				const enabledPacks = this.#packs.filter((pack) => isWordPackEnabled(pack.id, packValues));
+				this.#cachedPackWord = enabledPacks.length ? selectWorkingTextSelection(packValues, this.#packs, this.#poolFraction).text : this.#word;
+				this.#cachedPackSignature = signature;
+			}
+			word = this.#cachedPackWord;
 		}
 		let styledWord: string;
 		if (decorations.shimmer) {
@@ -106,13 +123,28 @@ export class PreviewRenderer {
 			tokenRate,
 		}, order);
 	}
-	private promptPreview(values: Record<string, boolean | string>): PreviewResult {
+	private packValues(values: Record<string, boolean | string>): Record<string, boolean> {
+		const enabled: Record<string, boolean> = {};
+		for (const pack of this.#packs) {
+			const value = values[`pack:${pack.id}`];
+			if (typeof value === "boolean") enabled[pack.id] = value;
+		}
+		return enabled;
+	}
+	private packPreview(id: string, values: Record<string, boolean | string>): PreviewResult {
+		const pack = this.#packs.find((candidate) => candidate.id === id);
+		if (!pack) return { lines: ["This word pack is unavailable."] };
+		const enabled = isWordPackEnabled(id, this.packValues(values));
+		const source = pack.bundled ? "Shipped example" : `Custom: ${wordPacksPath()}`;
+		return { lines: [`${pack.name}: ${enabled ? "enabled" : "disabled"}`, `${pack.words.length} phrases · ${source}`, ...(pack.description ? [pack.description] : [])] };
+	}
+	private promptPreview(values: Record<string, boolean | string>, width: number): PreviewResult {
 		if (values.decorateUserPrompt !== true) return { lines: ["User prompt decoration is disabled."] };
 
 		const borderColor = values.borderColor;
 		const borderStyle = values.borderStyle;
 		const timestamp = values.promptTimestamp === true ? Date.now() : undefined;
-		const lines = buildPromptBoxLines("ping", timestamp, PREVIEW_WIDTH, this.#ctx.ui.theme, {
+		const lines = buildPromptBoxLines("ping", timestamp, width, this.#ctx.ui.theme, {
 			showIcon: values.promptIcon === true,
 			showTimestamp: values.promptTimestamp === true,
 			showProvider: values.promptProvider === true,
@@ -127,7 +159,7 @@ export class PreviewRenderer {
 			? { lines }
 			: { lines, nextRefreshInMs: 1_000 - (timestamp % 1_000) };
 	}
-	private markerPreview(values: Record<string, boolean | string>): PreviewResult {
+	private markerPreview(values: Record<string, boolean | string>, width: number): PreviewResult {
 		if (values.doneMarker !== true) return { lines: ["Completion marker is disabled."] };
 		const theme = this.#ctx.ui.theme;
 		const icon = values.doneMarkerIcon === true ? theme.fg("text", values.useNerdFont === true ? "" : "π") : "";
@@ -138,7 +170,8 @@ export class PreviewRenderer {
 		const content = buildCompletionMarkerContent(theme, icon, word, "2m 52s", details);
 		const borderStyle = isDoneMarkerBorderStyle(values.doneMarkerBorderStyle) ? values.doneMarkerBorderStyle : "none";
 		const borderColor = isSettingColor(values.doneMarkerBorderColor) ? values.doneMarkerBorderColor : DEFAULT_SETTINGS.decorations.doneMarkerBorderColor;
-		const marker = buildCompletionMarkerLine(content, PREVIEW_WIDTH, theme, borderStyle, borderColor);
+		const markerStyle = isDoneMarkerStyle(values.doneMarkerStyle) ? values.doneMarkerStyle : DEFAULT_SETTINGS.decorations.doneMarkerStyle;
+		const marker = buildCompletionMarkerLine(content, width, theme, borderStyle, borderColor, markerStyle);
 		return { lines: ["", marker, ""] };
 	}
 }

package/src/prompt-decorator.ts

@@ -1,6 +1,7 @@
 import type { MessageRenderer, ThemeColor } from "@earendil-works/pi-coding-agent";
 import { truncateToWidth, visibleWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";
-import { DEFAULT_SETTINGS, isBorderStyle, isSettingColor, type BorderStyle, type DoneMarkerBorderStyle, type SettingColor } from "./settings.ts";
+import { DEFAULT_SETTINGS, isBorderStyle, isSettingColor, type BorderStyle, type DoneMarkerBorderStyle, type DoneMarkerStyle, type SettingColor } from "./settings.ts";
+import { stripControlChars } from "./util.ts";
 
 export const PROMPT_BOX_TYPE = "pi-topping-prompt";
 
@@ -32,11 +33,6 @@ type PromptTheme = { fg(color: string, text: string): string };
 
 const COMPLETION_MARKER_TRAIL_RUNS = [6, 4, 2, 1] as const;
 
-/** Strip control and formatting characters (bidi overrides, zero-width joiners, etc.) from untrusted single-line text. */
-export function stripControlChars(text: string): string {
-	return text.replace(/[\p{Cc}\p{Cf}]/gu, "");
-}
-
 /** Assemble the completion-marker content: an optional icon, then the dim `word for elapsed (details)` summary. */
 export function buildCompletionMarkerContent(
 	theme: PromptTheme,
@@ -56,6 +52,7 @@ export function buildCompletionMarkerLine(
 	theme: PromptTheme,
 	borderStyle: DoneMarkerBorderStyle,
 	borderColor: SettingColor,
+	markerStyle: DoneMarkerStyle = DEFAULT_SETTINGS.decorations.doneMarkerStyle,
 ): string {
 	const safeWidth = Math.max(0, Math.floor(width));
 	if (safeWidth === 0) return "";
@@ -63,8 +60,12 @@ export function buildCompletionMarkerLine(
 
 	const g = BORDER_GLYPHS[borderStyle];
 	const border = (text: string) => theme.fg(borderColor, text);
-	const trail = ` ${COMPLETION_MARKER_TRAIL_RUNS.map(length => g.h.repeat(length)).join(" ")}`;
-	const line = `${border(`${g.bl}${g.h.repeat(2)} `)}${content}${border(trail)}`;
+	const prefix = `${g.bl}${g.h.repeat(2)} `;
+
+	const suffix = markerStyle === "bookend"
+		? ` ${g.h.repeat(Math.max(0, safeWidth - visibleWidth(prefix) - visibleWidth(content) - 2))}${g.br}`
+		: ` ${COMPLETION_MARKER_TRAIL_RUNS.map(length => g.h.repeat(length)).join(" ")}`;
+	const line = `${border(prefix)}${content}${border(suffix)}`;
 	return visibleWidth(line) > safeWidth ? truncateToWidth(line, safeWidth) : line;
 }
 

package/src/session.ts

@@ -33,11 +33,15 @@ import {
 	TOKEN_RATE_PLACEHOLDER,
 	StreamingWordCounter,
 } from "./format.ts";
+import { isSiblingSetupEnabled } from "./flags.ts";
 import { showMenu } from "./menu.ts";
+import { registerSetupCommand } from "./setup-command.ts";
 import { applyMenuResult, buildMenuSections, loadSettings, saveSettings, type SettingColor } from "./settings.ts";
+import { notifyMissingToppingsOnce } from "./toppings.ts";
 import { PreviewRenderer } from "./preview.ts";
-import { buildCompletionMarkerContent, buildCompletionMarkerLine, PROMPT_BOX_TYPE, promptBoxRenderer, stripControlChars, type PromptBoxDetails } from "./prompt-decorator.ts";
-import { pickRandomWord, pickRawWord } from "./words.ts";
+import { buildCompletionMarkerContent, buildCompletionMarkerLine, PROMPT_BOX_TYPE, promptBoxRenderer, type PromptBoxDetails } from "./prompt-decorator.ts";
+import { stripControlChars } from "./util.ts";
+import { loadBundledWordPacks, loadUserWordPacks, pickWorkingTextSelection, type WorkingTextSelection, type WordPack } from "./word-packs.ts";
 
 type MessageStartEvent = Extract<ExtensionEvent, { type: "message_start" }>;
 type MessageUpdateEvent = Extract<ExtensionEvent, { type: "message_update" }>;
@@ -58,7 +62,7 @@ interface DoneEntryData {
 
 interface SessionState {
 	startTime: number;
-	currentWord: string;
+	workingText: WorkingTextSelection;
 	confirmTokens: number;
 	liveTokens: number;
 	shimmerOrigin: number;
@@ -90,7 +94,7 @@ function resetTokenRateState(state: SessionState): void {
 function makeFreshState(): SessionState {
 	return {
 		startTime: 0,
-		currentWord: "",
+		workingText: { text: "", pastTense: "Worked" },
 		confirmTokens: 0,
 		liveTokens: 0,
 		shimmerOrigin: 0,
@@ -112,6 +116,8 @@ export class SessionManager {
 	#counter = new StreamingWordCounter();
 	#state = makeFreshState();
 	#settings = loadSettings();
+	#userPacks: WordPack[] = [];
+	#bundledPacks = loadBundledWordPacks();
 	#currentCtx: ExtensionContext | null = null;
 	readonly #pi: ExtensionAPI;
 
@@ -124,9 +130,13 @@ export class SessionManager {
 		this.#counter.reset();
 		this.#state = makeFreshState();
 		this.#settings = loadSettings();
+		this.#userPacks = loadUserWordPacks();
 		this.#state.activityMeter.setDirection(this.#settings.decorations.meterDirection);
 		this.#currentCtx = ctx;
-		if (this.usable(ctx)) this.applyIndicator(ctx);
+		if (this.usable(ctx)) {
+			this.applyIndicator(ctx);
+			if (isSiblingSetupEnabled()) notifyMissingToppingsOnce(this.#pi, ctx.ui);
+		}
 	};
 
 	#onInput = async (event: InputEvent, ctx: ExtensionContext): Promise<InputEventResult | void> => {
@@ -209,7 +219,7 @@ export class SessionManager {
 	#onToolExecutionStart = async (_e: ToolExecutionStartEvent, ctx: ExtensionContext): Promise<void> => {
 		this.#currentCtx = ctx;
 		if (this.usable(ctx)) {
-			this.#state.currentWord = pickRandomWord();
+			this.#state.workingText = this.pickWorkingWord();
 			this.#state.shimmerOrigin = Date.now();
 			this.tick();
 		}
@@ -232,7 +242,7 @@ export class SessionManager {
 		this.#state.lastMessage = NOT_SENT;
 		if (this.#settings.features.doneMarker && hadPrompt) {
 			this.#pi.appendEntry<DoneEntryData>(DONE_ENTRY_TYPE, {
-				word: this.#settings.features.randomizeDoneMarker ? pickRawWord().past_tense : "Worked",
+				word: this.#settings.features.randomizeDoneMarker ? this.#state.workingText.pastTense : "Worked",
 				elapsedMs,
 				tokens: this.#state.confirmTokens,
 				midTurnInputs: this.#state.midTurnInputs,
@@ -259,6 +269,7 @@ export class SessionManager {
 		const markerContent = buildCompletionMarkerContent(theme, icon, word, formatElapsed(elapsedMs), details);
 		const borderStyle = this.#settings.decorations.doneMarkerBorderStyle;
 		const borderColor = this.#settings.decorations.doneMarkerBorderColor;
+		const markerStyle = this.#settings.decorations.doneMarkerStyle;
 		if (borderStyle === "none") return new Text(markerContent);
 
 		let cachedWidth: number | undefined;
@@ -267,7 +278,7 @@ export class SessionManager {
 			render(width: number): string[] {
 				if (cachedWidth !== width) {
 					cachedWidth = width;
-					cachedLines = ["", ` ${buildCompletionMarkerLine(markerContent, width - 2, theme, borderStyle, borderColor)}`, ""];
+					cachedLines = ["", buildCompletionMarkerLine(markerContent, width, theme, borderStyle, borderColor, markerStyle), ""];
 				}
 				return cachedLines!;
 			},
@@ -294,6 +305,7 @@ export class SessionManager {
 			description: "Configure prompt decoration, working-loader features/order, and completion-marker settings.",
 			handler: async (_a, ctx) => this.showSettings(ctx),
 		});
+		if (isSiblingSetupEnabled()) registerSetupCommand(this.#pi);
 	}
 
 	private usable(ctx: ExtensionContext): boolean {
@@ -367,11 +379,15 @@ export class SessionManager {
 		if (interval) this.#state.timer = setInterval(() => this.tick(), interval);
 	}
 
+	private pickWorkingWord(): WorkingTextSelection {
+		return pickWorkingTextSelection(this.#settings.wordPacks, [...this.#bundledPacks, ...this.#userPacks]);
+	}
+
 	private resetTurn(now: number): void {
 		const state = this.#state;
 		state.startTime = now;
 		state.shimmerOrigin = now;
-		state.currentWord = pickRandomWord();
+		state.workingText = this.pickWorkingWord();
 		state.confirmTokens = 0;
 		state.liveTokens = 0;
 		state.activityMeter.reset();
@@ -413,7 +429,7 @@ export class SessionManager {
 			return;
 		}
 
-		const word = features.substituteDefaultMessage ? state.currentWord : DEFAULT_WORKING_WORD;
+		const word = features.substituteDefaultMessage ? state.workingText.text : DEFAULT_WORKING_WORD;
 		const styled = decorations.shimmer
 			? shimmerString(word, now - state.shimmerOrigin, ctx.ui.theme, decorations.shimmerDirection, decorations.shimmerSpeed, decorations.shimmerInverted)
 			: ctx.ui.theme.fg("text", word);
@@ -476,11 +492,12 @@ export class SessionManager {
 			return;
 		}
 
+		this.#userPacks = loadUserWordPacks();
 		const before = this.indicatorFingerprint();
-		const preview = new PreviewRenderer(ctx);
+		const preview = new PreviewRenderer(ctx, [...this.#bundledPacks, ...this.#userPacks]);
 		const result = await showMenu<Record<string, boolean | string>>(ctx, {
 			title: "Pi Topping: Settings",
-			sections: buildMenuSections(this.#settings),
+			sections: buildMenuSections(this.#settings, this.#bundledPacks, this.#userPacks),
 			hints: ["↑↓ move", "←→ select", "␣ toggle", "⏎ apply", "esc cancel"],
 			preview: preview.render.bind(preview),
 		});