pi-usereq 0.7.0 → 0.11.0

package/pi.dev-src/pi-mono/coding-agent/src/migrations.ts

@@ -0,0 +1,314 @@
+/**
+ * One-time migrations that run on startup.
+ */
+
+import chalk from "chalk";
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "fs";
+import { dirname, join } from "path";
+import { CONFIG_DIR_NAME, getAgentDir, getBinDir } from "./config.js";
+import { migrateKeybindingsConfig } from "./core/keybindings.js";
+
+const MIGRATION_GUIDE_URL =
+	"https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/CHANGELOG.md#extensions-migration";
+const EXTENSIONS_DOC_URL = "https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/docs/extensions.md";
+
+/**
+ * Migrate legacy oauth.json and settings.json apiKeys to auth.json.
+ *
+ * @returns Array of provider names that were migrated
+ */
+export function migrateAuthToAuthJson(): string[] {
+	const agentDir = getAgentDir();
+	const authPath = join(agentDir, "auth.json");
+	const oauthPath = join(agentDir, "oauth.json");
+	const settingsPath = join(agentDir, "settings.json");
+
+	// Skip if auth.json already exists
+	if (existsSync(authPath)) return [];
+
+	const migrated: Record<string, unknown> = {};
+	const providers: string[] = [];
+
+	// Migrate oauth.json
+	if (existsSync(oauthPath)) {
+		try {
+			const oauth = JSON.parse(readFileSync(oauthPath, "utf-8"));
+			for (const [provider, cred] of Object.entries(oauth)) {
+				migrated[provider] = { type: "oauth", ...(cred as object) };
+				providers.push(provider);
+			}
+			renameSync(oauthPath, `${oauthPath}.migrated`);
+		} catch {
+			// Skip on error
+		}
+	}
+
+	// Migrate settings.json apiKeys
+	if (existsSync(settingsPath)) {
+		try {
+			const content = readFileSync(settingsPath, "utf-8");
+			const settings = JSON.parse(content);
+			if (settings.apiKeys && typeof settings.apiKeys === "object") {
+				for (const [provider, key] of Object.entries(settings.apiKeys)) {
+					if (!migrated[provider] && typeof key === "string") {
+						migrated[provider] = { type: "api_key", key };
+						providers.push(provider);
+					}
+				}
+				delete settings.apiKeys;
+				writeFileSync(settingsPath, JSON.stringify(settings, null, 2));
+			}
+		} catch {
+			// Skip on error
+		}
+	}
+
+	if (Object.keys(migrated).length > 0) {
+		mkdirSync(dirname(authPath), { recursive: true });
+		writeFileSync(authPath, JSON.stringify(migrated, null, 2), { mode: 0o600 });
+	}
+
+	return providers;
+}
+
+/**
+ * Migrate sessions from ~/.pi/agent/*.jsonl to proper session directories.
+ *
+ * Bug in v0.30.0: Sessions were saved to ~/.pi/agent/ instead of
+ * ~/.pi/agent/sessions/<encoded-cwd>/. This migration moves them
+ * to the correct location based on the cwd in their session header.
+ *
+ * See: https://github.com/badlogic/pi-mono/issues/320
+ */
+export function migrateSessionsFromAgentRoot(): void {
+	const agentDir = getAgentDir();
+
+	// Find all .jsonl files directly in agentDir (not in subdirectories)
+	let files: string[];
+	try {
+		files = readdirSync(agentDir)
+			.filter((f) => f.endsWith(".jsonl"))
+			.map((f) => join(agentDir, f));
+	} catch {
+		return;
+	}
+
+	if (files.length === 0) return;
+
+	for (const file of files) {
+		try {
+			// Read first line to get session header
+			const content = readFileSync(file, "utf8");
+			const firstLine = content.split("\n")[0];
+			if (!firstLine?.trim()) continue;
+
+			const header = JSON.parse(firstLine);
+			if (header.type !== "session" || !header.cwd) continue;
+
+			const cwd: string = header.cwd;
+
+			// Compute the correct session directory (same encoding as session-manager.ts)
+			const safePath = `--${cwd.replace(/^[/\\]/, "").replace(/[/\\:]/g, "-")}--`;
+			const correctDir = join(agentDir, "sessions", safePath);
+
+			// Create directory if needed
+			if (!existsSync(correctDir)) {
+				mkdirSync(correctDir, { recursive: true });
+			}
+
+			// Move the file
+			const fileName = file.split("/").pop() || file.split("\\").pop();
+			const newPath = join(correctDir, fileName!);
+
+			if (existsSync(newPath)) continue; // Skip if target exists
+
+			renameSync(file, newPath);
+		} catch {
+			// Skip files that can't be migrated
+		}
+	}
+}
+
+/**
+ * Migrate commands/ to prompts/ if needed.
+ * Works for both regular directories and symlinks.
+ */
+function migrateCommandsToPrompts(baseDir: string, label: string): boolean {
+	const commandsDir = join(baseDir, "commands");
+	const promptsDir = join(baseDir, "prompts");
+
+	if (existsSync(commandsDir) && !existsSync(promptsDir)) {
+		try {
+			renameSync(commandsDir, promptsDir);
+			console.log(chalk.green(`Migrated ${label} commands/ → prompts/`));
+			return true;
+		} catch (err) {
+			console.log(
+				chalk.yellow(
+					`Warning: Could not migrate ${label} commands/ to prompts/: ${err instanceof Error ? err.message : err}`,
+				),
+			);
+		}
+	}
+	return false;
+}
+
+function migrateKeybindingsConfigFile(): void {
+	const configPath = join(getAgentDir(), "keybindings.json");
+	if (!existsSync(configPath)) return;
+
+	try {
+		const parsed = JSON.parse(readFileSync(configPath, "utf-8")) as unknown;
+		if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+			return;
+		}
+		const { config, migrated } = migrateKeybindingsConfig(parsed as Record<string, unknown>);
+		if (!migrated) return;
+		writeFileSync(configPath, `${JSON.stringify(config, null, 2)}\n`, "utf-8");
+	} catch {
+		// Ignore malformed files during migration
+	}
+}
+
+/**
+ * Move fd/rg binaries from tools/ to bin/ if they exist.
+ */
+function migrateToolsToBin(): void {
+	const agentDir = getAgentDir();
+	const toolsDir = join(agentDir, "tools");
+	const binDir = getBinDir();
+
+	if (!existsSync(toolsDir)) return;
+
+	const binaries = ["fd", "rg", "fd.exe", "rg.exe"];
+	let movedAny = false;
+
+	for (const bin of binaries) {
+		const oldPath = join(toolsDir, bin);
+		const newPath = join(binDir, bin);
+
+		if (existsSync(oldPath)) {
+			if (!existsSync(binDir)) {
+				mkdirSync(binDir, { recursive: true });
+			}
+			if (!existsSync(newPath)) {
+				try {
+					renameSync(oldPath, newPath);
+					movedAny = true;
+				} catch {
+					// Ignore errors
+				}
+			} else {
+				// Target exists, just delete the old one
+				try {
+					rmSync?.(oldPath, { force: true });
+				} catch {
+					// Ignore
+				}
+			}
+		}
+	}
+
+	if (movedAny) {
+		console.log(chalk.green(`Migrated managed binaries tools/ → bin/`));
+	}
+}
+
+/**
+ * Check for deprecated hooks/ and tools/ directories.
+ * Note: tools/ may contain fd/rg binaries extracted by pi, so only warn if it has other files.
+ */
+function checkDeprecatedExtensionDirs(baseDir: string, label: string): string[] {
+	const hooksDir = join(baseDir, "hooks");
+	const toolsDir = join(baseDir, "tools");
+	const warnings: string[] = [];
+
+	if (existsSync(hooksDir)) {
+		warnings.push(`${label} hooks/ directory found. Hooks have been renamed to extensions.`);
+	}
+
+	if (existsSync(toolsDir)) {
+		// Check if tools/ contains anything other than fd/rg (which are auto-extracted binaries)
+		try {
+			const entries = readdirSync(toolsDir);
+			const customTools = entries.filter((e) => {
+				const lower = e.toLowerCase();
+				return (
+					lower !== "fd" && lower !== "rg" && lower !== "fd.exe" && lower !== "rg.exe" && !e.startsWith(".") // Ignore .DS_Store and other hidden files
+				);
+			});
+			if (customTools.length > 0) {
+				warnings.push(
+					`${label} tools/ directory contains custom tools. Custom tools have been merged into extensions.`,
+				);
+			}
+		} catch {
+			// Ignore read errors
+		}
+	}
+
+	return warnings;
+}
+
+/**
+ * Run extension system migrations (commands→prompts) and collect warnings about deprecated directories.
+ */
+function migrateExtensionSystem(cwd: string): string[] {
+	const agentDir = getAgentDir();
+	const projectDir = join(cwd, CONFIG_DIR_NAME);
+
+	// Migrate commands/ to prompts/
+	migrateCommandsToPrompts(agentDir, "Global");
+	migrateCommandsToPrompts(projectDir, "Project");
+
+	// Check for deprecated directories
+	const warnings = [
+		...checkDeprecatedExtensionDirs(agentDir, "Global"),
+		...checkDeprecatedExtensionDirs(projectDir, "Project"),
+	];
+
+	return warnings;
+}
+
+/**
+ * Print deprecation warnings and wait for keypress.
+ */
+export async function showDeprecationWarnings(warnings: string[]): Promise<void> {
+	if (warnings.length === 0) return;
+
+	for (const warning of warnings) {
+		console.log(chalk.yellow(`Warning: ${warning}`));
+	}
+	console.log(chalk.yellow(`\nMove your extensions to the extensions/ directory.`));
+	console.log(chalk.yellow(`Migration guide: ${MIGRATION_GUIDE_URL}`));
+	console.log(chalk.yellow(`Documentation: ${EXTENSIONS_DOC_URL}`));
+	console.log(chalk.dim(`\nPress any key to continue...`));
+
+	await new Promise<void>((resolve) => {
+		process.stdin.setRawMode?.(true);
+		process.stdin.resume();
+		process.stdin.once("data", () => {
+			process.stdin.setRawMode?.(false);
+			process.stdin.pause();
+			resolve();
+		});
+	});
+	console.log();
+}
+
+/**
+ * Run all migrations. Called once on startup.
+ *
+ * @returns Object with migration results and deprecation warnings
+ */
+export function runMigrations(cwd: string): {
+	migratedAuthProviders: string[];
+	deprecationWarnings: string[];
+} {
+	const migratedAuthProviders = migrateAuthToAuthJson();
+	migrateSessionsFromAgentRoot();
+	migrateToolsToBin();
+	migrateKeybindingsConfigFile();
+	const deprecationWarnings = migrateExtensionSystem(cwd);
+	return { migratedAuthProviders, deprecationWarnings };
+}

package/pi.dev-src/pi-mono/coding-agent/src/modes/index.ts

@@ -0,0 +1,9 @@
+/**
+ * Run modes for the coding agent.
+ */
+
+export { InteractiveMode, type InteractiveModeOptions } from "./interactive/interactive-mode.js";
+export { type PrintModeOptions, runPrintMode } from "./print-mode.js";
+export { type ModelInfo, RpcClient, type RpcClientOptions, type RpcEventListener } from "./rpc/rpc-client.js";
+export { runRpcMode } from "./rpc/rpc-mode.js";
+export type { RpcCommand, RpcResponse, RpcSessionState } from "./rpc/rpc-types.js";

package/pi.dev-src/pi-mono/coding-agent/src/modes/interactive/components/armin.ts

@@ -0,0 +1,382 @@
+/**
+ * Armin says hi! A fun easter egg with animated XBM art.
+ */
+
+import type { Component, TUI } from "@mariozechner/pi-tui";
+import { theme } from "../theme/theme.js";
+
+// XBM image: 31x36 pixels, LSB first, 1=background, 0=foreground
+const WIDTH = 31;
+const HEIGHT = 36;
+const BITS = [
+	0xff, 0xff, 0xff, 0x7f, 0xff, 0xf0, 0xff, 0x7f, 0xff, 0xed, 0xff, 0x7f, 0xff, 0xdb, 0xff, 0x7f, 0xff, 0xb7, 0xff,
+	0x7f, 0xff, 0x77, 0xfe, 0x7f, 0x3f, 0xf8, 0xfe, 0x7f, 0xdf, 0xff, 0xfe, 0x7f, 0xdf, 0x3f, 0xfc, 0x7f, 0x9f, 0xc3,
+	0xfb, 0x7f, 0x6f, 0xfc, 0xf4, 0x7f, 0xf7, 0x0f, 0xf7, 0x7f, 0xf7, 0xff, 0xf7, 0x7f, 0xf7, 0xff, 0xe3, 0x7f, 0xf7,
+	0x07, 0xe8, 0x7f, 0xef, 0xf8, 0x67, 0x70, 0x0f, 0xff, 0xbb, 0x6f, 0xf1, 0x00, 0xd0, 0x5b, 0xfd, 0x3f, 0xec, 0x53,
+	0xc1, 0xff, 0xef, 0x57, 0x9f, 0xfd, 0xee, 0x5f, 0x9f, 0xfc, 0xae, 0x5f, 0x1f, 0x78, 0xac, 0x5f, 0x3f, 0x00, 0x50,
+	0x6c, 0x7f, 0x00, 0xdc, 0x77, 0xff, 0xc0, 0x3f, 0x78, 0xff, 0x01, 0xf8, 0x7f, 0xff, 0x03, 0x9c, 0x78, 0xff, 0x07,
+	0x8c, 0x7c, 0xff, 0x0f, 0xce, 0x78, 0xff, 0xff, 0xcf, 0x7f, 0xff, 0xff, 0xcf, 0x78, 0xff, 0xff, 0xdf, 0x78, 0xff,
+	0xff, 0xdf, 0x7d, 0xff, 0xff, 0x3f, 0x7e, 0xff, 0xff, 0xff, 0x7f,
+];
+
+const BYTES_PER_ROW = Math.ceil(WIDTH / 8);
+const DISPLAY_HEIGHT = Math.ceil(HEIGHT / 2); // Half-block rendering
+
+type Effect = "typewriter" | "scanline" | "rain" | "fade" | "crt" | "glitch" | "dissolve";
+
+const EFFECTS: Effect[] = ["typewriter", "scanline", "rain", "fade", "crt", "glitch", "dissolve"];
+
+// Get pixel at (x, y): true = foreground, false = background
+function getPixel(x: number, y: number): boolean {
+	if (y >= HEIGHT) return false;
+	const byteIndex = y * BYTES_PER_ROW + Math.floor(x / 8);
+	const bitIndex = x % 8;
+	return ((BITS[byteIndex] >> bitIndex) & 1) === 0;
+}
+
+// Get the character for a cell (2 vertical pixels packed)
+function getChar(x: number, row: number): string {
+	const upper = getPixel(x, row * 2);
+	const lower = getPixel(x, row * 2 + 1);
+	if (upper && lower) return "█";
+	if (upper) return "▀";
+	if (lower) return "▄";
+	return " ";
+}
+
+// Build the final image grid
+function buildFinalGrid(): string[][] {
+	const grid: string[][] = [];
+	for (let row = 0; row < DISPLAY_HEIGHT; row++) {
+		const line: string[] = [];
+		for (let x = 0; x < WIDTH; x++) {
+			line.push(getChar(x, row));
+		}
+		grid.push(line);
+	}
+	return grid;
+}
+
+export class ArminComponent implements Component {
+	private ui: TUI;
+	private interval: ReturnType<typeof setInterval> | null = null;
+	private effect: Effect;
+	private finalGrid: string[][];
+	private currentGrid: string[][];
+	private effectState: Record<string, unknown> = {};
+	private cachedLines: string[] = [];
+	private cachedWidth = 0;
+	private gridVersion = 0;
+	private cachedVersion = -1;
+
+	constructor(ui: TUI) {
+		this.ui = ui;
+		this.effect = EFFECTS[Math.floor(Math.random() * EFFECTS.length)];
+		this.finalGrid = buildFinalGrid();
+		this.currentGrid = this.createEmptyGrid();
+
+		this.initEffect();
+		this.startAnimation();
+	}
+
+	invalidate(): void {
+		this.cachedWidth = 0;
+	}
+
+	render(width: number): string[] {
+		if (width === this.cachedWidth && this.cachedVersion === this.gridVersion) {
+			return this.cachedLines;
+		}
+
+		const padding = 1;
+		const availableWidth = width - padding;
+
+		this.cachedLines = this.currentGrid.map((row) => {
+			// Clip row to available width before applying color
+			const clipped = row.slice(0, availableWidth).join("");
+			const padRight = Math.max(0, width - padding - clipped.length);
+			return ` ${theme.fg("accent", clipped)}${" ".repeat(padRight)}`;
+		});
+
+		// Add "ARMIN SAYS HI" at the end
+		const message = "ARMIN SAYS HI";
+		const msgPadRight = Math.max(0, width - padding - message.length);
+		this.cachedLines.push(` ${theme.fg("accent", message)}${" ".repeat(msgPadRight)}`);
+
+		this.cachedWidth = width;
+		this.cachedVersion = this.gridVersion;
+
+		return this.cachedLines;
+	}
+
+	private createEmptyGrid(): string[][] {
+		return Array.from({ length: DISPLAY_HEIGHT }, () => Array(WIDTH).fill(" "));
+	}
+
+	private initEffect(): void {
+		switch (this.effect) {
+			case "typewriter":
+				this.effectState = { pos: 0 };
+				break;
+			case "scanline":
+				this.effectState = { row: 0 };
+				break;
+			case "rain":
+				// Track falling position for each column
+				this.effectState = {
+					drops: Array.from({ length: WIDTH }, () => ({
+						y: -Math.floor(Math.random() * DISPLAY_HEIGHT * 2),
+						settled: 0,
+					})),
+				};
+				break;
+			case "fade": {
+				// Shuffle all pixel positions
+				const positions: [number, number][] = [];
+				for (let row = 0; row < DISPLAY_HEIGHT; row++) {
+					for (let x = 0; x < WIDTH; x++) {
+						positions.push([row, x]);
+					}
+				}
+				// Fisher-Yates shuffle
+				for (let i = positions.length - 1; i > 0; i--) {
+					const j = Math.floor(Math.random() * (i + 1));
+					[positions[i], positions[j]] = [positions[j], positions[i]];
+				}
+				this.effectState = { positions, idx: 0 };
+				break;
+			}
+			case "crt":
+				this.effectState = { expansion: 0 };
+				break;
+			case "glitch":
+				this.effectState = { phase: 0, glitchFrames: 8 };
+				break;
+			case "dissolve": {
+				// Start with random noise
+				this.currentGrid = Array.from({ length: DISPLAY_HEIGHT }, () =>
+					Array.from({ length: WIDTH }, () => {
+						const chars = [" ", "░", "▒", "▓", "█", "▀", "▄"];
+						return chars[Math.floor(Math.random() * chars.length)];
+					}),
+				);
+				// Shuffle positions for gradual resolve
+				const dissolvePositions: [number, number][] = [];
+				for (let row = 0; row < DISPLAY_HEIGHT; row++) {
+					for (let x = 0; x < WIDTH; x++) {
+						dissolvePositions.push([row, x]);
+					}
+				}
+				for (let i = dissolvePositions.length - 1; i > 0; i--) {
+					const j = Math.floor(Math.random() * (i + 1));
+					[dissolvePositions[i], dissolvePositions[j]] = [dissolvePositions[j], dissolvePositions[i]];
+				}
+				this.effectState = { positions: dissolvePositions, idx: 0 };
+				break;
+			}
+		}
+	}
+
+	private startAnimation(): void {
+		const fps = this.effect === "glitch" ? 60 : 30;
+		this.interval = setInterval(() => {
+			const done = this.tickEffect();
+			this.updateDisplay();
+			this.ui.requestRender();
+			if (done) {
+				this.stopAnimation();
+			}
+		}, 1000 / fps);
+	}
+
+	private stopAnimation(): void {
+		if (this.interval) {
+			clearInterval(this.interval);
+			this.interval = null;
+		}
+	}
+
+	private tickEffect(): boolean {
+		switch (this.effect) {
+			case "typewriter":
+				return this.tickTypewriter();
+			case "scanline":
+				return this.tickScanline();
+			case "rain":
+				return this.tickRain();
+			case "fade":
+				return this.tickFade();
+			case "crt":
+				return this.tickCrt();
+			case "glitch":
+				return this.tickGlitch();
+			case "dissolve":
+				return this.tickDissolve();
+			default:
+				return true;
+		}
+	}
+
+	private tickTypewriter(): boolean {
+		const state = this.effectState as { pos: number };
+		const pixelsPerFrame = 3;
+
+		for (let i = 0; i < pixelsPerFrame; i++) {
+			const row = Math.floor(state.pos / WIDTH);
+			const x = state.pos % WIDTH;
+			if (row >= DISPLAY_HEIGHT) return true;
+			this.currentGrid[row][x] = this.finalGrid[row][x];
+			state.pos++;
+		}
+		return false;
+	}
+
+	private tickScanline(): boolean {
+		const state = this.effectState as { row: number };
+		if (state.row >= DISPLAY_HEIGHT) return true;
+
+		// Copy row
+		for (let x = 0; x < WIDTH; x++) {
+			this.currentGrid[state.row][x] = this.finalGrid[state.row][x];
+		}
+		state.row++;
+		return false;
+	}
+
+	private tickRain(): boolean {
+		const state = this.effectState as {
+			drops: { y: number; settled: number }[];
+		};
+
+		let allSettled = true;
+		this.currentGrid = this.createEmptyGrid();
+
+		for (let x = 0; x < WIDTH; x++) {
+			const drop = state.drops[x];
+
+			// Draw settled pixels
+			for (let row = DISPLAY_HEIGHT - 1; row >= DISPLAY_HEIGHT - drop.settled; row--) {
+				if (row >= 0) {
+					this.currentGrid[row][x] = this.finalGrid[row][x];
+				}
+			}
+
+			// Check if this column is done
+			if (drop.settled >= DISPLAY_HEIGHT) continue;
+
+			allSettled = false;
+
+			// Find the target row for this column (lowest non-space pixel)
+			let targetRow = -1;
+			for (let row = DISPLAY_HEIGHT - 1 - drop.settled; row >= 0; row--) {
+				if (this.finalGrid[row][x] !== " ") {
+					targetRow = row;
+					break;
+				}
+			}
+
+			// Move drop down
+			drop.y++;
+
+			// Draw falling drop
+			if (drop.y >= 0 && drop.y < DISPLAY_HEIGHT) {
+				if (targetRow >= 0 && drop.y >= targetRow) {
+					// Settle
+					drop.settled = DISPLAY_HEIGHT - targetRow;
+					drop.y = -Math.floor(Math.random() * 5) - 1;
+				} else {
+					// Still falling
+					this.currentGrid[drop.y][x] = "▓";
+				}
+			}
+		}
+
+		return allSettled;
+	}
+
+	private tickFade(): boolean {
+		const state = this.effectState as { positions: [number, number][]; idx: number };
+		const pixelsPerFrame = 15;
+
+		for (let i = 0; i < pixelsPerFrame; i++) {
+			if (state.idx >= state.positions.length) return true;
+			const [row, x] = state.positions[state.idx];
+			this.currentGrid[row][x] = this.finalGrid[row][x];
+			state.idx++;
+		}
+		return false;
+	}
+
+	private tickCrt(): boolean {
+		const state = this.effectState as { expansion: number };
+		const midRow = Math.floor(DISPLAY_HEIGHT / 2);
+
+		this.currentGrid = this.createEmptyGrid();
+
+		// Draw from middle expanding outward
+		const top = midRow - state.expansion;
+		const bottom = midRow + state.expansion;
+
+		for (let row = Math.max(0, top); row <= Math.min(DISPLAY_HEIGHT - 1, bottom); row++) {
+			for (let x = 0; x < WIDTH; x++) {
+				this.currentGrid[row][x] = this.finalGrid[row][x];
+			}
+		}
+
+		state.expansion++;
+		return state.expansion > DISPLAY_HEIGHT;
+	}
+
+	private tickGlitch(): boolean {
+		const state = this.effectState as { phase: number; glitchFrames: number };
+
+		if (state.phase < state.glitchFrames) {
+			// Glitch phase: show corrupted version
+			this.currentGrid = this.finalGrid.map((row) => {
+				const offset = Math.floor(Math.random() * 7) - 3;
+				const glitchRow = [...row];
+
+				// Random horizontal offset
+				if (Math.random() < 0.3) {
+					const shifted = glitchRow.slice(offset).concat(glitchRow.slice(0, offset));
+					return shifted.slice(0, WIDTH);
+				}
+
+				// Random vertical swap
+				if (Math.random() < 0.2) {
+					const swapRow = Math.floor(Math.random() * DISPLAY_HEIGHT);
+					return [...this.finalGrid[swapRow]];
+				}
+
+				return glitchRow;
+			});
+			state.phase++;
+			return false;
+		}
+
+		// Final frame: show clean image
+		this.currentGrid = this.finalGrid.map((row) => [...row]);
+		return true;
+	}
+
+	private tickDissolve(): boolean {
+		const state = this.effectState as { positions: [number, number][]; idx: number };
+		const pixelsPerFrame = 20;
+
+		for (let i = 0; i < pixelsPerFrame; i++) {
+			if (state.idx >= state.positions.length) return true;
+			const [row, x] = state.positions[state.idx];
+			this.currentGrid[row][x] = this.finalGrid[row][x];
+			state.idx++;
+		}
+		return false;
+	}
+
+	private updateDisplay(): void {
+		this.gridVersion++;
+	}
+
+	dispose(): void {
+		this.stopAnimation();
+	}
+}