@underactive/pi-topping 0.5.1 → 0.6.0

package/src/settings.ts

@@ -3,6 +3,8 @@ import { mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "
 import { dirname, join } from "node:path";
 import { DEFAULT_LOADER_ORDER, type LoaderElement } from "./format.ts";
 import type { MenuSection } from "./menu.ts";
+import { isWordPackEnabled, isWordPackId, type WordPack } from "./word-packs.ts";
+import { isPlainObject } from "./util.ts";
 
 export const SETTING_COLOR_VALUES = ["accent", "border", "borderAccent", "success", "error", "warning"] as const;
 export type SettingColor = (typeof SETTING_COLOR_VALUES)[number];
@@ -11,6 +13,8 @@ export const BORDER_STYLE_VALUES = ["double", "single", "rounded", "heavy"] as c
 export type BorderStyle = (typeof BORDER_STYLE_VALUES)[number];
 export const DONE_MARKER_BORDER_STYLE_VALUES = [...BORDER_STYLE_VALUES, "none"] as const;
 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 function isBorderStyle(value: unknown): value is BorderStyle {
 	return typeof value === "string" && BORDER_STYLE_VALUES.some(style => style === value);
@@ -20,6 +24,10 @@ export function isDoneMarkerBorderStyle(value: unknown): value is DoneMarkerBord
 	return typeof value === "string" && DONE_MARKER_BORDER_STYLE_VALUES.some(style => style === value);
 }
 
+export function isDoneMarkerStyle(value: unknown): value is DoneMarkerStyle {
+	return typeof value === "string" && DONE_MARKER_STYLE_VALUES.some(style => style === value);
+}
+
 export function isSettingColor(value: unknown): value is SettingColor {
 	return typeof value === "string" && SETTING_COLOR_VALUES.some(color => color === value);
 }
@@ -43,6 +51,7 @@ export interface DecoratorSettings {
 		borderStyleEnabled: boolean;
 		doneMarkerBorderStyle: DoneMarkerBorderStyle;
 		doneMarkerBorderColor: SettingColor;
+		doneMarkerStyle: DoneMarkerStyle;
 		spinnerColor: SettingColor;
 		spinnerColorEnabled: boolean;
 		meterColor: SettingColor;
@@ -68,12 +77,14 @@ export interface DecoratorSettings {
 		doneMarkerInputs: boolean;
 	};
 	loaderOrder: LoaderElement[];
+	wordPacks: Record<string, boolean>;
 }
 
 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: "borderAccent", borderColorEnabled: true, borderStyle: "double", borderStyleEnabled: true, doneMarkerBorderStyle: "none", doneMarkerBorderColor: "borderAccent", spinnerColor: "accent", spinnerColorEnabled: true, meterColor: "accent", meterColorEnabled: true, meterDimmed: false, tokenRateColor: "warning", tokenRateDimmed: 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: "borderAccent", borderColorEnabled: true, borderStyle: "double", borderStyleEnabled: true, doneMarkerBorderStyle: "none", doneMarkerBorderColor: "borderAccent", doneMarkerStyle: "elite", spinnerColor: "accent", spinnerColorEnabled: true, meterColor: "accent", meterColorEnabled: true, meterDimmed: false, tokenRateColor: "warning", tokenRateDimmed: false, promptIcon: true, promptTimestamp: true, promptProvider: true, promptModel: true, useNerdFont: true },
 	features: { substituteDefaultMessage: true, elapsedTime: true, outputTokens: true, tokenRate: true, doneMarker: true, doneMarkerIcon: true, randomizeDoneMarker: true, doneMarkerTokens: true, doneMarkerInputs: true },
 	loaderOrder: [...DEFAULT_LOADER_ORDER],
+	wordPacks: {},
 };
 
 /** Menu key carrying the loader element order as a comma-joined list of element ids. */
@@ -104,7 +115,6 @@ export function parseLoaderOrder(value: unknown): LoaderElement[] {
 }
 
 export function settingsPath(): string { return join(getAgentDir(), "pi-topping", "settings.json"); }
-function isPlainObject(value: unknown): value is Record<string, unknown> { return typeof value === "object" && value !== null && !Array.isArray(value); }
 function mergeGroup<T extends Record<string, boolean | string>>(defaults: T, parsed: unknown): T {
 	const merged = { ...defaults };
 	if (!isPlainObject(parsed)) return merged;
@@ -117,6 +127,7 @@ function mergeGroup<T extends Record<string, boolean | string>>(defaults: T, par
 		else if (key.endsWith("Color") && isSettingColor(value)) valid = value;
 		else if (key === "borderStyle" && isBorderStyle(value)) valid = value;
 		else if (key === "doneMarkerBorderStyle" && isDoneMarkerBorderStyle(value)) valid = value;
+		else if (key === "doneMarkerStyle" && isDoneMarkerStyle(value)) valid = value;
 		if (valid !== undefined) (merged as Record<string, boolean | string>)[key] = valid;
 	}
 	return merged;
@@ -188,6 +199,7 @@ export const MENU_ENTRIES: readonly MenuEntry[] = [
 	{ id: "tokenRateColor", label: "Token rate color", section: "“Working” Loader", group: "decorations", key: "tokenRateColor", cycleValues: SETTING_COLOR_VALUES },
 	{ id: "tokenRateDimmed", label: "Token rate dimmed", section: "“Working” Loader", group: "decorations", key: "tokenRateDimmed" },
 	{ id: "doneMarker", label: "Show completion marker", section: "Completion Marker", group: "features", key: "doneMarker" },
+	{ id: "doneMarkerStyle", label: "Marker style", section: "Completion Marker", group: "decorations", key: "doneMarkerStyle", cycleValues: DONE_MARKER_STYLE_VALUES },
 	{ id: "doneMarkerBorderStyle", label: "Border style", section: "Completion Marker", group: "decorations", key: "doneMarkerBorderStyle", cycleValues: DONE_MARKER_BORDER_STYLE_VALUES },
 	{ id: "doneMarkerBorderColor", label: "Border color", section: "Completion Marker", group: "decorations", key: "doneMarkerBorderColor", cycleValues: SETTING_COLOR_VALUES },
 	{ id: "doneMarkerIcon", label: "Pi icon", section: "Completion Marker", group: "features", key: "doneMarkerIcon" },
@@ -225,6 +237,9 @@ function setDecorationCycleValue(decorations: DecorationSettings, key: keyof Dec
 		case "doneMarkerBorderStyle":
 			if (isDoneMarkerBorderStyle(stored)) decorations[key] = stored;
 			return;
+		case "doneMarkerStyle":
+			if (isDoneMarkerStyle(stored)) decorations[key] = stored;
+			return;
 		case "shimmerDirection":
 		case "meterDirection":
 			if (stored === "ltr" || stored === "rtl") decorations[key] = stored;
@@ -242,12 +257,14 @@ function buildSection(title: MenuSectionName, settings: DecoratorSettings): Menu
 	return { title, items: MENU_ENTRIES.filter(entry => entry.section === title).map(entry => menuItem(entry, settings)) };
 }
 
-export function buildMenuSections(settings: DecoratorSettings): MenuSection[] {
+export function buildMenuSections(settings: DecoratorSettings, bundledPacks: readonly WordPack[], userPacks: readonly WordPack[] = []): MenuSection[] {
+	const packs = [...bundledPacks, ...userPacks];
 	return [
 		buildSection("User Prompt", settings),
 		buildSection("“Working” Loader", settings),
 		{ title: "Elements Order", items: parseLoaderOrder(settings.loaderOrder).map(id => ({ id, label: LOADER_ELEMENT_LABELS[id], value: false, reorderGroup: LOADER_ORDER_ID })) },
 		buildSection("Completion Marker", settings),
+		{ title: "Word Packs", items: packs.map((pack) => ({ id: `pack:${pack.id}`, label: pack.name, value: isWordPackEnabled(pack.id, settings.wordPacks) })) },
 		buildSection("Options", settings),
 	];
 }
@@ -266,6 +283,11 @@ export function applyMenuResult(settings: DecoratorSettings, values: Record<stri
 			next.features[entry.key] = value;
 		}
 	}
+	for (const [id, value] of Object.entries(values)) {
+		if (!id.startsWith("pack:") || typeof value !== "boolean") continue;
+		const packId = id.slice("pack:".length);
+		if (isWordPackId(packId)) next.wordPacks[packId] = value;
+	}
 	if (typeof values[LOADER_ORDER_ID] === "string") next.loaderOrder = parseLoaderOrder(values[LOADER_ORDER_ID]);
 	return next;
 }
@@ -280,7 +302,16 @@ export function loadSettings(): DecoratorSettings {
 	try {
 		const parsed = JSON.parse(readFileSync(settingsPath(), "utf8"));
 		if (!isPlainObject(parsed)) return structuredClone(DEFAULT_SETTINGS);
-		const settings = { decorations: mergeGroup(DEFAULT_SETTINGS.decorations, parsed.decorations), features: mergeGroup(DEFAULT_SETTINGS.features, parsed.features), loaderOrder: parseLoaderOrder(parsed.loaderOrder) };
+		const wordPacks: Record<string, boolean> = { ...DEFAULT_SETTINGS.wordPacks };
+		if (isPlainObject(parsed.wordPacks)) {
+			for (const [id, enabled] of Object.entries(parsed.wordPacks)) {
+				if (isWordPackId(id) && typeof enabled === "boolean") wordPacks[id] = enabled;
+			}
+		}
+		if (isPlainObject(parsed.features) && parsed.features.simCityWorkingText === true && !("simcity" in wordPacks)) {
+			wordPacks.simcity = true;
+		}
+		const settings = { decorations: mergeGroup(DEFAULT_SETTINGS.decorations, parsed.decorations), features: mergeGroup(DEFAULT_SETTINGS.features, parsed.features), loaderOrder: parseLoaderOrder(parsed.loaderOrder), wordPacks };
 		for (const entry of MENU_ENTRIES) {
 			if (entry.group === "decorations" && entry.cycleEnabledBy && entry.cycleDisabledValue !== undefined && !settings.decorations[entry.cycleEnabledBy]) {
 				setDecorationCycleValue(settings.decorations, entry.key, entry.cycleDisabledValue);
@@ -290,15 +321,18 @@ export function loadSettings(): DecoratorSettings {
 	} catch { return structuredClone(DEFAULT_SETTINGS); }
 }
 
-export function saveSettings(settings: DecoratorSettings): void {
-	const path = settingsPath();
+export function atomicWriteFile(path: string, contents: string): void {
 	mkdirSync(dirname(path), { recursive: true });
 	const tmpPath = `${path}.${process.pid}.${Date.now()}.tmp`;
 	try {
-		writeFileSync(tmpPath, `${JSON.stringify(settings, null, 2)}\n`, { flag: "wx" });
+		writeFileSync(tmpPath, contents, { flag: "wx" });
 		renameSync(tmpPath, path);
 	} catch (err) {
 		try { unlinkSync(tmpPath); } catch { /* tmp file was never created */ }
 		throw err;
 	}
 }
+
+export function saveSettings(settings: DecoratorSettings): void {
+	atomicWriteFile(settingsPath(), `${JSON.stringify(settings, null, 2)}\n`);
+}

package/src/setup-check.ts

@@ -0,0 +1,20 @@
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { join } from "node:path";
+import { readFileSync } from "node:fs";
+import { atomicWriteFile } from "./settings.ts";
+import { isPlainObject } from "./util.ts";
+
+const setupCheckPath = (): string => join(getAgentDir(), "pi-topping", "setup-check.json");
+
+export function isSetupCheckDisabled(): boolean {
+	try {
+		const parsed: unknown = JSON.parse(readFileSync(setupCheckPath(), "utf8"));
+		return isPlainObject(parsed) && parsed.disabled === true;
+	} catch {
+		return false;
+	}
+}
+
+export function setSetupCheckDisabled(disabled: boolean): void {
+	atomicWriteFile(setupCheckPath(), `${JSON.stringify({ disabled })}\n`);
+}

package/src/setup-command.ts

@@ -0,0 +1,136 @@
+import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { hyperlink } from "@earendil-works/pi-tui";
+import { showMenu } from "./menu.ts";
+import { type PiInstallResult, spawnPiInstall } from "./pi-installer.ts";
+import { stripControlChars } from "./util.ts";
+import { setSetupCheckDisabled } from "./setup-check.ts";
+import { findMissingToppings, type ToppingStatus } from "./toppings.ts";
+
+const INSTALL_TIMEOUT_MS = 120_000;
+const STDERR_SNIPPET_CHARS = 300;
+
+type ToppingInstaller = (spec: string, timeoutMs: number) => Promise<PiInstallResult>;
+
+type FailedInstall = { spec: string; error: string };
+
+function selectedToppings(missing: readonly ToppingStatus[], values: Record<string, boolean>): ToppingStatus[] {
+	return missing.filter(({ topping }) => values[topping.pkg] === true);
+}
+
+function renderDescription(missing: readonly ToppingStatus[], activeItemId: string | undefined): string[] {
+	const active = missing.find(({ topping }) => topping.pkg === activeItemId);
+	if (!active) return ["Select a topping to see what it does."];
+	const url = `https://pi.dev/packages/${active.topping.pkg}`;
+	return [active.topping.provides, "", hyperlink(url, url)];
+}
+
+function errorMessage(error: unknown): string {
+	return error instanceof Error ? error.message : String(error);
+}
+
+function buildReport(succeeded: string[], failed: FailedInstall[]): string {
+	const lines: string[] = [];
+	if (succeeded.length > 0) lines.push(`✓ Installed: ${succeeded.join(", ")}`);
+	if (failed.length > 0) {
+		lines.push("✗ Failed:");
+		for (const failure of failed) lines.push(`  ${failure.spec}: ${failure.error}`);
+	}
+	if (succeeded.length > 0) {
+		lines.push("");
+		lines.push("Restart Pi afterwards to activate them.");
+	}
+	return lines.join("\n");
+}
+
+async function installSelected(
+	ctx: ExtensionCommandContext,
+	selected: readonly ToppingStatus[],
+	install: ToppingInstaller,
+): Promise<{ succeeded: string[]; failed: FailedInstall[] }> {
+	const succeeded: string[] = [];
+	const failed: FailedInstall[] = [];
+	for (const { topping } of selected) {
+		const spec = `npm:${topping.pkg}`;
+		ctx.ui.notify(`Installing ${spec}…`, "info");
+		try {
+			const result = await install(spec, INSTALL_TIMEOUT_MS);
+			if (result.code === 0) {
+				succeeded.push(spec);
+			} else {
+				failed.push({ spec, error: stripControlChars((result.stderr || result.stdout || `exit ${result.code}`).trim()).slice(0, STDERR_SNIPPET_CHARS) });
+			}
+		} catch (error) {
+			failed.push({ spec, error: stripControlChars(errorMessage(error)).slice(0, STDERR_SNIPPET_CHARS) });
+		}
+	}
+	return { succeeded, failed };
+}
+
+export function registerSetupCommand(pi: ExtensionAPI, install: ToppingInstaller = spawnPiInstall): void {
+	pi.registerCommand("topping-setup", {
+		description: "Install missing Pi Topping sibling extensions or manage the missing-extension notice.",
+		handler: async (args, ctx) => {
+			const action = args.trim();
+			if (action === "disable-side-toppings-check" || action === "enable-side-toppings-check") {
+				try {
+					const disabled = action === "disable-side-toppings-check";
+					setSetupCheckDisabled(disabled);
+					ctx.ui.notify(
+						disabled
+							? "Missing topping check disabled. Run `/topping-setup enable-side-toppings-check` to re-enable it."
+							: "Missing topping check enabled.",
+						"info",
+					);
+				} catch {
+					ctx.ui.notify(`Failed to ${action === "disable-side-toppings-check" ? "disable" : "enable"} the missing topping check.`, "error");
+				}
+				return;
+			}
+			if (action) {
+				ctx.ui.notify("Usage: /topping-setup [disable-side-toppings-check|enable-side-toppings-check]", "error");
+				return;
+			}
+
+			if (ctx.mode !== "tui") {
+				ctx.ui.notify("/topping-setup requires TUI mode", "error");
+				return;
+			}
+
+			const missing = findMissingToppings(pi);
+			if (missing.length === 0) {
+				ctx.ui.notify("All Pi Topping extensions are already active in this session.", "info");
+				return;
+			}
+
+			const result = await showMenu<Record<string, boolean>>(ctx, {
+				title: "Pi Topping: Setup",
+				sections: [
+					{
+						title: "Missing Toppings",
+						items: missing.map(({ topping, onDisk }) => ({
+							id: topping.pkg,
+							label: `${topping.pkg}${onDisk ? " (on disk, not active)" : ""}`,
+							value: true,
+						})),
+					},
+				],
+				hints: ["↑↓ move", "␣ toggle", "⏎ install", "esc cancel"],
+				previewTitle: "Description",
+				preview: (_values, _elapsedMs, activeItemId) => ({ lines: renderDescription(missing, activeItemId) }),
+			});
+			if (!result.applied) {
+				ctx.ui.notify("Pi Topping setup cancelled.", "info");
+				return;
+			}
+
+			const selected = selectedToppings(missing, result.values);
+			if (selected.length === 0) {
+				ctx.ui.notify("No Pi Topping extensions selected.", "info");
+				return;
+			}
+
+			const { succeeded, failed } = await installSelected(ctx, selected, install);
+			ctx.ui.notify(buildReport(succeeded, failed), failed.length > 0 ? "warning" : "info");
+		},
+	});
+}

package/src/toppings.ts

@@ -0,0 +1,158 @@
+import { getAgentDir, type ExtensionAPI, type ExtensionUIContext } from "@earendil-works/pi-coding-agent";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { isSetupCheckDisabled } from "./setup-check.ts";
+import { isPlainObject } from "./util.ts";
+
+export interface Topping {
+	readonly pkg: string;
+	readonly matches: RegExp;
+	readonly dir: string;
+	readonly provides: string;
+}
+
+export interface ToppingStatus {
+	readonly topping: Topping;
+	readonly active: boolean;
+	readonly onDisk: boolean;
+}
+
+export const TOPPINGS: readonly Topping[] = [
+	{
+		pkg: "@underactive/pi-topping-statusline",
+		matches: /pi-topping-statusline/i,
+		dir: "pi-topping-statusline",
+		provides: "status line customization",
+	},
+	{
+		pkg: "@underactive/pi-topping-splash",
+		matches: /pi-topping-splash/i,
+		dir: "pi-topping-splash",
+		provides: "startup splash screen",
+	},
+	{
+		pkg: "@underactive/pi-topping-persona-audit",
+		matches: /pi-topping-persona-audit/i,
+		dir: "pi-topping-persona-audit",
+		provides: "persona audit tools",
+	},
+	{
+		pkg: "@underactive/pi-topping-web-tools",
+		matches: /pi-topping-web-tools/i,
+		dir: "pi-topping-web-tools",
+		provides: "web research and browser automation",
+	},
+];
+
+interface PiSettings {
+	packages?: unknown;
+	extensions?: unknown;
+}
+
+interface SettingsToppingState {
+	packageInstalled: boolean;
+	extensionPresent: boolean;
+	extensionActive: boolean;
+}
+
+let setupNoticeHandled = false;
+
+function stringEntries(value: unknown): string[] {
+	return Array.isArray(value) ? value.filter((entry): entry is string => typeof entry === "string") : [];
+}
+
+function readPiSettings(): PiSettings | undefined {
+	try {
+		const parsed: unknown = JSON.parse(readFileSync(join(getAgentDir(), "settings.json"), "utf8"));
+		return isPlainObject(parsed) ? parsed as PiSettings : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+function extensionEntry(entry: string): { value: string; disabled: boolean } {
+	const value = entry.trim();
+	if (value.startsWith("+") || value.startsWith("-")) return { value: value.slice(1), disabled: value.startsWith("-") };
+	return { value, disabled: false };
+}
+
+function settingsState(settings: PiSettings | undefined, topping: Topping): SettingsToppingState {
+	let packageInstalled = false;
+	let extensionPresent = false;
+	let extensionActive = false;
+	for (const entry of stringEntries(settings?.packages)) {
+		if (topping.matches.test(entry)) packageInstalled = true;
+	}
+	for (const entry of stringEntries(settings?.extensions)) {
+		const normalized = extensionEntry(entry);
+		if (!topping.matches.test(normalized.value)) continue;
+		extensionPresent = true;
+		if (!normalized.disabled) extensionActive = true;
+	}
+	return { packageInstalled, extensionPresent, extensionActive };
+}
+
+function runtimeActiveToppings(pi: ExtensionAPI): Array<true | undefined> | undefined {
+	try {
+		const commands = pi.getCommands();
+		return TOPPINGS.map((topping) =>
+			commands.some((command) =>
+				command.source === "extension" && topping.matches.test(command.sourceInfo.path),
+			)
+				? true
+				: undefined,
+		);
+	} catch {
+		// The extension runtime has not yet been bound during initial load.
+		return undefined;
+	}
+}
+
+export function detectToppings(pi: ExtensionAPI): ToppingStatus[] {
+	const runtime = runtimeActiveToppings(pi);
+	const settings = readPiSettings();
+	const extensionsDir = join(getAgentDir(), "extensions");
+	return TOPPINGS.map((topping, index) => {
+		const configured = settingsState(settings, topping);
+		const checkoutPresent = existsSync(join(extensionsDir, topping.dir));
+		const onDisk = configured.packageInstalled || configured.extensionPresent || checkoutPresent;
+		const fallbackActive = configured.packageInstalled || configured.extensionActive || checkoutPresent;
+		return { topping, active: runtime?.[index] ?? fallbackActive, onDisk };
+	});
+}
+
+export function findMissingToppings(pi: ExtensionAPI): ToppingStatus[] {
+	return detectToppings(pi).filter((status) => !status.active);
+}
+
+function renderMissingBanner(missing: readonly ToppingStatus[]): string {
+	const title = `pi-topping: ${missing.length} topping extensions missing`;
+	const body = [
+		...missing.map(({ topping }) => `• ${topping.pkg} — ${topping.provides}`),
+		"",
+		"Run `/topping-setup` to selectively install them",
+		"Run `/topping-setup disable-side-toppings-check` to suppress this message",
+	];
+	const width = Math.max(title.length + 6, ...body.map((line) => line.length + 4));
+	const blankRow = `│${" ".repeat(width - 2)}│`;
+	return [
+		`╭─ ${title} ${"─".repeat(width - title.length - 5)}╮`,
+		blankRow,
+		...body.map((line) => `│ ${line.padEnd(width - 4)} │`),
+		blankRow,
+		`╰${"─".repeat(width - 2)}╯`,
+	].join("\n");
+}
+
+export function notifyMissingToppingsOnce(pi: ExtensionAPI, ui: Pick<ExtensionUIContext, "notify">): void {
+	if (setupNoticeHandled) return;
+	setupNoticeHandled = true;
+	if (isSetupCheckDisabled()) return;
+	const missing = findMissingToppings(pi);
+	if (missing.length > 0) ui.notify(`\n${renderMissingBanner(missing)}`, "warning");
+}
+
+/** Test-only reset for the once-per-process session-start notice. */
+export function __resetSetupNotice(): void {
+	setupNoticeHandled = false;
+}

package/src/util.ts

@@ -0,0 +1,9 @@
+/** True for object records, excluding arrays and null. */
+export function isPlainObject(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** Strip control and formatting characters from untrusted single-line text. */
+export function stripControlChars(text: string): string {
+	return text.replace(/[\p{Cc}\p{Cf}]/gu, "");
+}

package/src/word-packs.ts

@@ -0,0 +1,119 @@
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { readdirSync, readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { join } from "node:path";
+import { isPlainObject, stripControlChars } from "./util.ts";
+import { WORDS, type WordEntry } from "./words.ts";
+
+const PACK_ID_PATTERN = /^[a-z][a-z0-9-]{0,63}$/;
+const RESERVED_BUNDLED_PACK_IDS = new Set(["simcity", "star-trek", "star-wars"]);
+
+export function isWordPackId(value: string): boolean { return PACK_ID_PATTERN.test(value); }
+const BUNDLED_PACK_DIRECTORY = fileURLToPath(new URL("../wordpacks/", import.meta.url));
+
+export interface WordPack {
+	id: string;
+	name: string;
+	description?: string;
+	attribution?: string;
+	words: readonly WordEntry[];
+	bundled: boolean;
+}
+
+export interface WorkingTextSelection {
+	text: string;
+	pastTense: string;
+}
+
+export function wordPacksPath(): string {
+	return join(getAgentDir(), "pi-topping", "word-packs.json");
+}
+
+function safeText(value: unknown): string | undefined {
+	if (typeof value !== "string") return undefined;
+	const text = stripControlChars(value).trim();
+	return text || undefined;
+}
+
+/** Validate a pack document, discarding invalid packs and entries. */
+export function parseWordPacks(value: unknown, bundled = false): WordPack[] {
+	if (!isPlainObject(value)) return [];
+	const rawPacks = Array.isArray(value.packs) ? value.packs : [value];
+	const packs: WordPack[] = [];
+	const ids = new Set<string>();
+	for (const rawPack of rawPacks) {
+		if (!isPlainObject(rawPack)) continue;
+		const id = safeText(rawPack.id);
+		const name = safeText(rawPack.name);
+		if (!id || !name || !isWordPackId(id) || ids.has(id) || (!bundled && RESERVED_BUNDLED_PACK_IDS.has(id))) continue;
+		const words: WordEntry[] = [];
+		if (Array.isArray(rawPack.words)) {
+			for (const rawWord of rawPack.words) {
+				if (!isPlainObject(rawWord)) continue;
+				const present_tense = safeText(rawWord.present_tense);
+				const past_tense = safeText(rawWord.past_tense);
+				if (present_tense && past_tense) words.push({ present_tense, past_tense });
+			}
+		}
+		if (!words.length) continue;
+		ids.add(id);
+		const description = safeText(rawPack.description);
+		const attribution = safeText(rawPack.attribution);
+		packs.push({ id, name, ...(description ? { description } : {}), ...(attribution ? { attribution } : {}), words, bundled });
+	}
+	return packs;
+}
+
+/** Load every shipped JSON pack. Missing or invalid bundled data is a package-integrity error. */
+export function loadBundledWordPacks(): WordPack[] {
+	const files = readdirSync(BUNDLED_PACK_DIRECTORY).filter((file) => file.endsWith(".json")).sort();
+	const packs: WordPack[] = [];
+	const ids = new Set<string>();
+	for (const file of files) {
+		let value: unknown;
+		try {
+			value = JSON.parse(readFileSync(join(BUNDLED_PACK_DIRECTORY, file), "utf8"));
+		} catch (error) {
+			throw new Error(`Invalid bundled word pack: ${file}`, { cause: error });
+		}
+		const parsed = parseWordPacks(value, true);
+		if (!parsed.length) throw new Error(`Invalid bundled word pack: ${file}`);
+		for (const pack of parsed) {
+			if (ids.has(pack.id)) throw new Error(`Duplicate bundled word pack ID: ${pack.id}`);
+			ids.add(pack.id);
+			packs.push(pack);
+		}
+	}
+	if (!packs.some((pack) => pack.id === "simcity")) throw new Error("Missing bundled SimCity word pack");
+	const bundledIds = new Set(packs.map((pack) => pack.id));
+	for (const id of RESERVED_BUNDLED_PACK_IDS) {
+		if (!bundledIds.has(id)) throw new Error(`Missing bundled word pack: ${id}`);
+	}
+	for (const id of bundledIds) {
+		if (!RESERVED_BUNDLED_PACK_IDS.has(id)) throw new Error(`Bundled word pack "${id}" must be listed in RESERVED_BUNDLED_PACK_IDS to prevent user-pack shadowing`);
+	}
+	return packs;
+}
+
+/** User pack failures are intentionally non-fatal. */
+export function loadUserWordPacks(): WordPack[] {
+	try {
+		return parseWordPacks(JSON.parse(readFileSync(wordPacksPath(), "utf8")));
+	} catch {
+		return [];
+	}
+}
+
+export function isWordPackEnabled(id: string, enabled: Record<string, boolean>): boolean {
+	return enabled[id] === true;
+}
+
+export function selectWorkingTextSelection(enabled: Record<string, boolean>, packs: readonly WordPack[], fraction: number): WorkingTextSelection {
+	const pool = [...WORDS, ...packs.filter((pack) => isWordPackEnabled(pack.id, enabled)).flatMap((pack) => pack.words)];
+	const entry = pool[Math.min(pool.length - 1, Math.floor(fraction * pool.length))]!;
+	return { text: `${entry.present_tense}…`, pastTense: entry.past_tense };
+}
+
+export function pickWorkingTextSelection(enabled: Record<string, boolean>, packs: readonly WordPack[]): WorkingTextSelection {
+	return selectWorkingTextSelection(enabled, packs, Math.random());
+}