@openlines/opl-pi-sht 0.1.14

package/extensions/opl-input/index.ts

@@ -0,0 +1,284 @@
+import { CustomEditor, type ExtensionAPI, type Theme } from "@earendil-works/pi-coding-agent";
+import type { TUI, EditorTheme } from "@earendil-works/pi-tui";
+import type { KeybindingsManager } from "@earendil-works/pi-coding-agent";
+import { visibleWidth } from "@earendil-works/pi-tui";
+import { CONFIG, COMPANION_PADDING, MIN_WIDTH_FOR_COMPANION } from "./config.js";
+import { resolveModeStyle, type ModeAppearance } from "./mode-style.js";
+import { applyColor, CompanionAnimator } from "./utils.js";
+
+// ─── Helpers ──────────────────────────────────────────────────────────────
+const ANSI_RE = /\x1b\[[0-9;]*m|\x1b\[0?m/g;
+
+function plainText(line: string): string {
+	return line.replace(ANSI_RE, "");
+}
+
+function activeMode(): { mode: string; appearance?: ModeAppearance } {
+	const state = (globalThis as Record<string, unknown>).__agentMode as
+		| { mode?: string; appearance?: ModeAppearance }
+		| undefined;
+	return { mode: state?.mode ?? "off", appearance: state?.appearance };
+}
+
+// ─── Component ────────────────────────────────────────────────────────────
+class ChatInput extends CustomEditor {
+	private companionColor: (s: string) => string;
+	// Full Theme (not EditorTheme): custom-mode colors resolve through theme.fg,
+	// which EditorTheme does not implement.
+	private uiTheme: Theme;
+	private inputTheme: EditorTheme;
+	private animator = new CompanionAnimator();
+	private companionTimer: ReturnType<typeof setInterval> | null = null;
+
+	constructor(
+		tui: TUI,
+		theme: EditorTheme,
+		keybindings: KeybindingsManager,
+		companionColor: (s: string) => string,
+		uiTheme: Theme,
+	) {
+		super(tui, theme, keybindings, { paddingX: 0 });
+		this.companionColor = companionColor;
+		this.uiTheme = uiTheme;
+		this.inputTheme = theme;
+
+		// Animate companion even when idle — tick drives state machine
+		this.companionTimer = setInterval(() => {
+			this.animator.tick(Date.now());
+			this.tui.requestRender();
+		}, 100);
+	}
+
+	private isBashMode(): boolean {
+		const text = (this as any).getText?.();
+		return typeof text === "string" && text.trimStart().startsWith("!");
+	}
+
+	render(width: number): string[] {
+		const padMultiplier = CONFIG.BOXED_VIEW ? 3 : 1;
+		if (width < 5 + CONFIG.BOX_PAD_X * padMultiplier) return super.render(width);
+
+		const contentWidth = CONFIG.BOXED_VIEW
+			? width - 3 - CONFIG.BOX_PAD_X * 3
+			: width - 2 * CONFIG.BOX_PAD_X - 1;
+		const stock = super.render(contentWidth);
+		if (stock.length < 2) return super.render(width);
+
+		const isBash = this.isBashMode();
+		const mode = activeMode();
+		const style = resolveModeStyle({ bash: isBash, mode: mode.mode, appearance: mode.appearance });
+		const border = (s: string) => applyColor(this.uiTheme, style.borderColor, s);
+		const accent = (s: string) => applyColor(this.uiTheme, style.prefixColor, s);
+		const prefix = style.prefix;
+
+		if (CONFIG.BOXED_VIEW) {
+			return this.renderBoxed(stock, contentWidth, width, border, accent, prefix);
+		}
+		return this.renderUnboxed(stock, contentWidth, width, border, accent, prefix);
+	}
+
+	private buildCompanionLines(width: number): string[] {
+		if (!CONFIG.COMPANION_ENABLED || width < MIN_WIDTH_FOR_COMPANION) return [];
+
+		const state = this.animator.getState();
+		const artWidth = Math.max(...state.lines.map(l => visibleWidth(l)), 0);
+		const rawPad = width - COMPANION_PADDING - artWidth + state.extraPad;
+		// Clamp: never negative, never exceed terminal width
+		const pad = Math.max(0, Math.min(rawPad, width - artWidth));
+		const spaces = " ".repeat(pad);
+
+		const lines: string[] = [];
+		for (const line of state.lines) {
+			lines.push(spaces + this.companionColor(line));
+		}
+		const topPadding = CONFIG.COMPANION_ENABLED ? CONFIG.COMPANION_TOP_PADDING : 0;
+		// Reserve topPadding lines so chat bar doesn't jump — art anchored to bottom
+		while (lines.length < topPadding) {
+			lines.unshift("");
+		}
+		return lines;
+	}
+
+	private renderBoxed(
+		stock: string[],
+		contentWidth: number,
+		width: number,
+		border: (s: string) => string,
+		accent: (s: string) => string,
+		prefix: string,
+	): string[] {
+		const innerWidth = width - 2;
+
+		// Solid border: after stripping ANSI every char is "─"
+		const isSolidBorder = (line: string) => plainText(line).replace(/─/g, "").length === 0;
+
+		// Scroll indicator: starts with "─" and contains ↑/↓ N more
+		const getScrollText = (line: string): string | null => {
+			const plain = plainText(line);
+			if (!plain.startsWith("─")) return null;
+			const m = plain.match(/((?:↑|↓)\s*\d+\s*more)/);
+			return m ? m[1] : null;
+		};
+
+		const isBorderLike = (line: string) => isSolidBorder(line) || getScrollText(line) !== null;
+
+		const firstIdx = stock.findIndex(isBorderLike);
+		let lastIdx = -1;
+		for (let i = stock.length - 1; i >= 0; i--) {
+			if (isBorderLike(stock[i]!)) {
+				lastIdx = i;
+				break;
+			}
+		}
+
+		// Build top/bottom box borders, embedding scroll indicator text when present
+		const buildTop = (scrollText: string | null): string => {
+			if (!scrollText) return border("┌") + border("─".repeat(innerWidth)) + border("┐");
+			const mid = `── ${scrollText} `;
+			const remaining = Math.max(0, innerWidth - visibleWidth(mid));
+			return border("┌") + border(mid) + border("─".repeat(remaining)) + border("┐");
+		};
+
+		const buildBottom = (scrollText: string | null): string => {
+			if (!scrollText) return border("└") + border("─".repeat(innerWidth)) + border("┘");
+			const mid = `── ${scrollText} `;
+			const remaining = Math.max(0, innerWidth - visibleWidth(mid));
+			return border("└") + border(mid) + border("─".repeat(remaining)) + border("┘");
+		};
+
+		const topScrollText = firstIdx !== -1 ? getScrollText(stock[firstIdx]!) : null;
+		const bottomScrollText = lastIdx !== -1 && lastIdx !== firstIdx ? getScrollText(stock[lastIdx]!) : null;
+
+		const top = buildTop(topScrollText);
+		const bottom = buildBottom(bottomScrollText);
+
+		// ── companion art ──
+		const companionLines = this.buildCompanionLines(width);
+
+		const leftPad = " ".repeat(CONFIG.BOX_PAD_X);
+		const rightPad = leftPad;
+
+		// ── body lines (between first and last border/indicator) ──
+		const body: string[] = [];
+		let isFirstBodyLine = true;
+		for (let i = 0; i < stock.length; i++) {
+			if (i === firstIdx || i === lastIdx) continue;
+			if (lastIdx !== -1 && i > lastIdx) continue;
+
+			const vw = visibleWidth(stock[i]!);
+			const pad = vw < contentWidth ? " ".repeat(contentWidth - vw) : "";
+			const prefixStr = isFirstBodyLine ? accent(prefix) : " ";
+			body.push(border("│") + leftPad + prefixStr + leftPad + stock[i]! + pad + rightPad + border("│"));
+			isFirstBodyLine = false;
+		}
+
+		// ── menu lines (after last border/indicator) ──
+		const menu: string[] = [];
+		if (lastIdx !== -1) {
+			for (let i = lastIdx + 1; i < stock.length; i++) {
+				const vw = visibleWidth(stock[i]!);
+				const indent = " ".repeat(CONFIG.EXTRA_MENU_INDENT);
+				const pad = vw + CONFIG.EXTRA_MENU_INDENT < width ? " ".repeat(width - vw - CONFIG.EXTRA_MENU_INDENT) : "";
+				menu.push(indent + stock[i]! + pad);
+			}
+		}
+
+		const gap = Array.from({ length: CONFIG.MENU_GAP }, () => "");
+		return [...companionLines, top, ...body, bottom, ...gap, ...menu];
+	}
+
+	private renderUnboxed(
+		stock: string[],
+		contentWidth: number,
+		width: number,
+		border: (s: string) => string,
+		accent: (s: string) => string,
+		prefix: string,
+	): string[] {
+		// Solid border: after stripping ANSI every char is "─"
+		const isSolidBorder = (line: string) => plainText(line).replace(/─/g, "").length === 0;
+
+		// Scroll indicator: starts with "─" and contains ↑/↓ N more
+		const getScrollText = (line: string): string | null => {
+			const plain = plainText(line);
+			if (!plain.startsWith("─")) return null;
+			const m = plain.match(/((?:↑|↓)\s*\d+\s*more)/);
+			return m ? m[1] : null;
+		};
+
+		const isBorderLike = (line: string) => isSolidBorder(line) || getScrollText(line) !== null;
+
+		const firstIdx = stock.findIndex(isBorderLike);
+		let lastIdx = -1;
+		for (let i = stock.length - 1; i >= 0; i--) {
+			if (isBorderLike(stock[i]!)) {
+				lastIdx = i;
+				break;
+			}
+		}
+
+		// Build top/bottom horizontal borders only (no corners, no sides)
+		const buildTop = (scrollText: string | null): string => {
+			if (!scrollText) return border("─".repeat(width));
+			const mid = `── ${scrollText} `;
+			const remaining = Math.max(0, width - visibleWidth(mid));
+			return border(mid) + border("─".repeat(remaining));
+		};
+
+		const buildBottom = (scrollText: string | null): string => {
+			if (!scrollText) return border("─".repeat(width));
+			const mid = `── ${scrollText} `;
+			const remaining = Math.max(0, width - visibleWidth(mid));
+			return border(mid) + border("─".repeat(remaining));
+		};
+
+		const topScrollText = firstIdx !== -1 ? getScrollText(stock[firstIdx]!) : null;
+		const bottomScrollText = lastIdx !== -1 && lastIdx !== firstIdx ? getScrollText(stock[lastIdx]!) : null;
+
+		const top = buildTop(topScrollText);
+		const bottom = buildBottom(bottomScrollText);
+
+		// ── companion art ──
+		const companionLines = this.buildCompanionLines(width);
+
+		const leftPad = " ".repeat(CONFIG.BOX_PAD_X);
+
+		// ── body lines ──
+		const body: string[] = [];
+		let isFirstBodyLine = true;
+		for (let i = 0; i < stock.length; i++) {
+			if (i === firstIdx || i === lastIdx) continue;
+			if (lastIdx !== -1 && i > lastIdx) continue;
+
+			const vw = visibleWidth(stock[i]!);
+			const pad = vw < contentWidth ? " ".repeat(contentWidth - vw) : "";
+			const prefixStr = isFirstBodyLine ? accent(prefix) : " ";
+			body.push(leftPad + prefixStr + leftPad + stock[i]! + pad);
+			isFirstBodyLine = false;
+		}
+
+		// ── menu lines ──
+		const menu: string[] = [];
+		if (lastIdx !== -1) {
+			for (let i = lastIdx + 1; i < stock.length; i++) {
+				const vw = visibleWidth(stock[i]!);
+				const indent = " ".repeat(CONFIG.EXTRA_MENU_INDENT);
+				const pad = vw + CONFIG.EXTRA_MENU_INDENT < width ? " ".repeat(width - vw - CONFIG.EXTRA_MENU_INDENT) : "";
+				menu.push(indent + stock[i]! + pad);
+			}
+		}
+
+		const gap = Array.from({ length: CONFIG.MENU_GAP }, () => "");
+		return [...companionLines, top, ...body, bottom, ...gap, ...menu];
+	}
+}
+
+// ─── Extension entry ──────────────────────────────────────────────────────
+export default function (pi: ExtensionAPI) {
+	pi.on("session_start", async (_event, ctx) => {
+		ctx.ui.setEditorComponent((tui: TUI, theme: EditorTheme, kb: KeybindingsManager) => {
+			const companionColorFn = (s: string) => applyColor(ctx.ui.theme, CONFIG.COMPANION_COLOR, s);
+			return new ChatInput(tui, theme, kb, companionColorFn, ctx.ui.theme);
+		});
+	});
+}

package/extensions/opl-input/mode-style.ts

@@ -0,0 +1,38 @@
+// Pure mode-to-style resolution for opl-input. No external imports so it can
+// be unit-tested directly (tests/opl-input-style.test.mjs).
+
+export interface ModeAppearance {
+	prefix?: string;
+	prefixColor?: string;
+	borderColor?: string;
+}
+
+export interface ModeState {
+	bash: boolean;
+	mode: string;
+	appearance?: ModeAppearance;
+}
+
+export interface ResolvedModeStyle {
+	borderColor: string;
+	prefixColor: string;
+	prefix: string;
+}
+
+const MODE_DEFAULTS: Record<string, Required<ModeAppearance>> = {
+	off: { prefix: "❯", prefixColor: "accent", borderColor: "border" },
+	chat: { prefix: "»", prefixColor: "chatModeBorder", borderColor: "chatModeBorder" },
+	plan: { prefix: "⏸", prefixColor: "customMessageLabel", borderColor: "customMessageLabel" },
+	execute: { prefix: "⏸", prefixColor: "customMessageLabel", borderColor: "customMessageLabel" },
+};
+
+/** Precedence: bash > active mode appearance > hardcoded mode fallback. */
+export function resolveModeStyle(state: ModeState): ResolvedModeStyle {
+	const fallback = MODE_DEFAULTS[state.mode] ?? MODE_DEFAULTS.off;
+	if (state.bash) return { borderColor: "bashMode", prefixColor: "bashMode", prefix: fallback.prefix };
+	return {
+		borderColor: state.appearance?.borderColor ?? fallback.borderColor,
+		prefixColor: state.appearance?.prefixColor ?? fallback.prefixColor,
+		prefix: state.appearance?.prefix ?? fallback.prefix,
+	};
+}

package/extensions/opl-input/utils.ts

@@ -0,0 +1,378 @@
+import type { Theme, ThemeColor } from "@earendil-works/pi-coding-agent";
+import {
+	COMPANION_ARTS,
+	BLINK_ART,
+	DIP_INTERVAL_MS,
+	RISE_INTERVAL_MS,
+	EARS_MIN_DURATION_MS,
+	EARS_MAX_DURATION_MS,
+	FULL_MIN_DURATION_MS,
+	FULL_MAX_DURATION_MS,
+	NONE_MIN_DURATION_MS,
+	NONE_MAX_DURATION_MS,
+	FACE_MIN_DURATION_MS,
+	FACE_MAX_DURATION_MS,
+	EXPR_MIN_DURATION_MS,
+	EXPR_MAX_DURATION_MS,
+	STARE_MIN_DURATION_MS,
+	STARE_MAX_DURATION_MS,
+	STARE_CHANCE,
+	BLINK_MIN_DURATION_MS,
+	BLINK_MAX_DURATION_MS,
+	EXPR_BLINK_CHANCE,
+	EXPR_DOUBLE_BLINK_CHANCE,
+	DOUBLE_BLINK_GAP_MIN_MS,
+	DOUBLE_BLINK_GAP_MAX_MS,
+	WOBBLE_RANGE,
+	WOBBLE_MIN_INTERVAL_MS,
+	WOBBLE_MAX_INTERVAL_MS,
+	DIR_STEPS_MIN,
+	DIR_STEPS_MAX,
+	EDGE_BIAS_STRENGTH,
+	EDGE_PAUSE_MIN_MS,
+	EDGE_PAUSE_MAX_MS,
+	FACE_DRIFT_RANGE,
+	FACE_DRIFT_MIN_INTERVAL_MS,
+	FACE_DRIFT_MAX_INTERVAL_MS,
+	EARS_TO_NONE_CHANCE,
+	EARS_TO_FULL_CHANCE,
+	FULL_TO_EARS_CHANCE,
+	FULL_TO_NONE_CHANCE,
+	SLOW_TRANSITION_CHANCE,
+	SLOW_TRANSITION_MULT_MIN,
+	SLOW_TRANSITION_MULT_MAX,
+} from "./config.js";
+
+function isHexColor(color: string): boolean {
+	return color.startsWith("#");
+}
+
+function hexToAnsi(hex: string): string {
+	const h = hex.replace("#", "");
+	if (!/^[0-9a-fA-F]{6}$/.test(h)) return "";
+	const r = parseInt(h.slice(0, 2), 16);
+	const g = parseInt(h.slice(2, 4), 16);
+	const b = parseInt(h.slice(4, 6), 16);
+	return `\x1b[38;2;${r};${g};${b}m`;
+}
+
+export function applyColor(theme: Theme, color: string, text: string): string {
+	if (isHexColor(color)) {
+		return `${hexToAnsi(color)}${text}\x1b[0m`;
+	}
+	try {
+		return theme.fg(color as ThemeColor, text);
+	} catch {
+		// Color not defined in current theme — fall back to 'border'
+		try {
+			return theme.fg("border" as ThemeColor, text);
+		} catch {
+			return text; // no color at all rather than crash
+		}
+	}
+}
+
+// ─── Companion animator ───────────────────────────────────────────────────
+
+export interface CompanionState {
+	lines: string[];
+	extraPad: number;
+}
+
+type Phase = "face" | "ears" | "full" | "none";
+
+const TICK_MS = 100; // matches setInterval in ChatInput
+const R = (min: number, max: number) => min + Math.random() * (max - min);
+
+export class CompanionAnimator {
+	private phase: Phase = "face";
+	private phaseEntered = 0;
+	private phaseDuration = 0;
+
+	private exprIdx = 0;
+	private lastExprChange = 0;
+	private exprDuration = 0;
+	private isBlinking = false;
+	private blinkUntil = 0;
+
+	private doubleBlinkPending = false;
+	private doubleBlinkGap = false;
+	private gapUntil = 0;
+
+	private offset = 0;
+	private lastOffsetChange = 0;
+	private wobbleInterval = 0;
+
+	private dirDelta = 0;
+	private dirSteps = 0;
+
+	private edgePauseUntil = 0;
+
+	private lastFaceDrift = 0;
+	private faceDriftInterval = 0;
+
+	private transitionFromLines = 2;
+	private transitionRemaining = 0;
+	private transitionTotal = 0;
+
+	// ── tick ──────────────────────────────────────────────────────────
+
+	tick(now: number): void {
+		if (this.phaseEntered === 0) {
+			this.phaseEntered = now;
+			this.phaseDuration = R(FACE_MIN_DURATION_MS, FACE_MAX_DURATION_MS);
+			this.exprIdx = this.pickNextExpr();
+			this.lastExprChange = now;
+			this.exprDuration = this.randExprDuration();
+			this.lastFaceDrift = now;
+			this.faceDriftInterval = R(FACE_DRIFT_MIN_INTERVAL_MS, FACE_DRIFT_MAX_INTERVAL_MS);
+			return;
+		}
+
+		if (this.transitionRemaining > 0) this.transitionRemaining--;
+
+		const elapsed = now - this.phaseEntered;
+
+		if (this.phase === "face" || this.phase === "full") {
+			this.tickExpression(now);
+		}
+
+		switch (this.phase) {
+			case "face":  this.tickFace(now, elapsed);  break;
+			case "ears":  this.tickEars(now, elapsed);  break;
+			case "full":  this.tickFull(now, elapsed);  break;
+			case "none":  this.tickNone(elapsed);       break;
+		}
+	}
+
+	// ── expression cycling ────────────────────────────────────────────
+
+	private tickExpression(now: number): void {
+		if (this.doubleBlinkGap && now >= this.gapUntil) {
+			this.doubleBlinkGap = false;
+			this.isBlinking = true;
+			this.blinkUntil = now + R(BLINK_MIN_DURATION_MS, BLINK_MAX_DURATION_MS);
+			return;
+		}
+
+		if (this.isBlinking && now >= this.blinkUntil) {
+			this.isBlinking = false;
+			if (this.doubleBlinkPending) {
+				this.doubleBlinkPending = false;
+				this.doubleBlinkGap = true;
+				this.gapUntil = now + R(DOUBLE_BLINK_GAP_MIN_MS, DOUBLE_BLINK_GAP_MAX_MS);
+			} else {
+				this.exprIdx = this.pickNextExpr();
+				this.exprDuration = this.randExprDuration();
+				this.lastExprChange = now;
+			}
+			return;
+		}
+
+		if (!this.isBlinking && !this.doubleBlinkGap && now - this.lastExprChange >= this.exprDuration) {
+			const roll = Math.random();
+			this.lastExprChange = now;
+			if (roll < EXPR_BLINK_CHANCE) {
+				this.isBlinking = true;
+				this.blinkUntil = now + R(BLINK_MIN_DURATION_MS, BLINK_MAX_DURATION_MS);
+			} else if (roll < EXPR_BLINK_CHANCE + EXPR_DOUBLE_BLINK_CHANCE) {
+				this.isBlinking = true;
+				this.blinkUntil = now + R(BLINK_MIN_DURATION_MS, BLINK_MAX_DURATION_MS);
+				this.doubleBlinkPending = true;
+			} else {
+				this.exprIdx = this.pickNextExpr();
+				this.exprDuration = this.randExprDuration();
+			}
+		}
+	}
+
+	// ── face ──────────────────────────────────────────────────────────
+
+	private tickFace(now: number, elapsed: number): void {
+		if (now - this.lastFaceDrift >= this.faceDriftInterval) {
+			const delta = Math.random() < 0.5 ? -1 : 1;
+			this.offset = Math.max(-FACE_DRIFT_RANGE, Math.min(FACE_DRIFT_RANGE, this.offset + delta));
+			this.lastFaceDrift = now;
+			this.faceDriftInterval = R(FACE_DRIFT_MIN_INTERVAL_MS, FACE_DRIFT_MAX_INTERVAL_MS);
+		}
+
+		if (elapsed < this.phaseDuration) return;
+		const dipProb = TICK_MS / DIP_INTERVAL_MS;
+		const riseProb = TICK_MS / RISE_INTERVAL_MS;
+		const roll = Math.random();
+
+		if (roll < dipProb) {
+			this.enterEars(now);
+		} else if (roll < dipProb + riseProb) {
+			this.enterFull(now);
+		}
+	}
+
+	// ── ears ──────────────────────────────────────────────────────────
+
+	private tickEars(now: number, elapsed: number): void {
+		if (now < this.edgePauseUntil) {
+			if (elapsed >= this.phaseDuration) this.finishEars(now);
+			return;
+		}
+
+		if (now - this.lastOffsetChange >= this.wobbleInterval) {
+			if (this.dirSteps <= 0) this.startRun();
+
+			const next = this.offset + this.dirDelta;
+			if (next > WOBBLE_RANGE || next < -WOBBLE_RANGE) {
+				this.offset = this.dirDelta > 0 ? WOBBLE_RANGE : -WOBBLE_RANGE;
+				this.edgePauseUntil = now + R(EDGE_PAUSE_MIN_MS, EDGE_PAUSE_MAX_MS);
+				this.dirSteps = 0;
+			} else {
+				this.offset = next;
+				this.dirSteps--;
+			}
+			this.lastOffsetChange = now;
+			this.wobbleInterval = R(WOBBLE_MIN_INTERVAL_MS, WOBBLE_MAX_INTERVAL_MS);
+		}
+
+		if (elapsed >= this.phaseDuration) this.finishEars(now);
+	}
+
+	private startRun(): void {
+		if (this.offset >= WOBBLE_RANGE) {
+			this.dirDelta = -1;
+		} else if (this.offset <= -WOBBLE_RANGE) {
+			this.dirDelta = 1;
+		} else {
+			const edgeRatio = Math.abs(this.offset) / WOBBLE_RANGE;
+			const awayChance = 0.5 + edgeRatio * EDGE_BIAS_STRENGTH;
+			if (Math.random() < awayChance) {
+				this.dirDelta = this.offset > 0 ? -1 : 1;
+			} else {
+				this.dirDelta = this.offset > 0 ? 1 : -1;
+			}
+		}
+		this.dirSteps = DIR_STEPS_MIN + Math.floor(Math.random() * (DIR_STEPS_MAX - DIR_STEPS_MIN + 1));
+	}
+
+	private finishEars(now: number): void {
+		const roll = Math.random();
+		if (roll < EARS_TO_NONE_CHANCE) {
+			this.enterNone(now);
+		} else if (roll < EARS_TO_NONE_CHANCE + EARS_TO_FULL_CHANCE) {
+			this.enterFull(now);
+		} else {
+			this.enterFace(now);
+		}
+	}
+
+	// ── full ──────────────────────────────────────────────────────────
+
+	private tickFull(now: number, elapsed: number): void {
+		if (elapsed < this.phaseDuration) return;
+		const roll = Math.random();
+		if (roll < FULL_TO_EARS_CHANCE) {
+			this.enterEars(now);
+		} else if (roll < FULL_TO_EARS_CHANCE + FULL_TO_NONE_CHANCE) {
+			this.enterNone(now);
+		} else {
+			this.enterFace(now);
+		}
+	}
+
+	// ── none (hidden) ─────────────────────────────────────────────────
+
+	private tickNone(elapsed: number): void {
+		if (elapsed >= this.phaseDuration) this.enterFace(Date.now());
+	}
+
+	// ── transitions ───────────────────────────────────────────────────
+
+	private enterEars(now: number): void {
+		this.switchPhase("ears", now);
+		this.phaseDuration = R(EARS_MIN_DURATION_MS, EARS_MAX_DURATION_MS);
+		this.lastOffsetChange = now;
+		this.wobbleInterval = R(WOBBLE_MIN_INTERVAL_MS, WOBBLE_MAX_INTERVAL_MS);
+		this.dirSteps = 0;
+		this.edgePauseUntil = 0;
+	}
+
+	private enterFull(now: number): void {
+		this.switchPhase("full", now);
+		this.phaseDuration = R(FULL_MIN_DURATION_MS, FULL_MAX_DURATION_MS);
+	}
+
+	private enterFace(now: number): void {
+		this.switchPhase("face", now);
+		this.phaseDuration = R(FACE_MIN_DURATION_MS, FACE_MAX_DURATION_MS);
+		this.lastFaceDrift = now;
+		this.faceDriftInterval = R(FACE_DRIFT_MIN_INTERVAL_MS, FACE_DRIFT_MAX_INTERVAL_MS);
+	}
+
+	private enterNone(now: number): void {
+		this.switchPhase("none", now);
+		this.phaseDuration = R(NONE_MIN_DURATION_MS, NONE_MAX_DURATION_MS);
+	}
+
+	private switchPhase(newPhase: Phase, now: number): void {
+		this.transitionFromLines = this.visibleLineCount();
+		this.phase = newPhase;
+		this.phaseEntered = now;
+		const toLines = this.visibleLineCount();
+		const lineDiff = Math.abs(toLines - this.transitionFromLines);
+		const slow = lineDiff > 0 && Math.random() < SLOW_TRANSITION_CHANCE;
+		const mult = slow
+			? SLOW_TRANSITION_MULT_MIN + Math.floor(Math.random() * (SLOW_TRANSITION_MULT_MAX - SLOW_TRANSITION_MULT_MIN + 1))
+			: 1;
+		this.transitionRemaining = lineDiff * mult;
+		this.transitionTotal = this.transitionRemaining;
+	}
+
+	private visibleLineCount(): number {
+		switch (this.phase) {
+			case "none": return 0;
+			case "ears": return 1;
+			case "face": return 2;
+			case "full": return 3;
+		}
+	}
+
+	// ── randomisers ───────────────────────────────────────────────────
+
+	private pickNextExpr(): number {
+		if (COMPANION_ARTS.length <= 1) return 0;
+		let next: number;
+		do {
+			next = Math.floor(Math.random() * COMPANION_ARTS.length);
+		} while (next === this.exprIdx);
+		return next;
+	}
+
+	private randExprDuration(): number {
+		if (Math.random() < STARE_CHANCE) {
+			return R(STARE_MIN_DURATION_MS, STARE_MAX_DURATION_MS);
+		}
+		return R(EXPR_MIN_DURATION_MS, EXPR_MAX_DURATION_MS);
+	}
+
+	// ── render state ──────────────────────────────────────────────────
+
+	getState(): CompanionState {
+		const art = COMPANION_ARTS[this.exprIdx]!;
+		const targetLines = this.visibleLineCount();
+
+		let lineCount: number;
+		if (this.transitionRemaining > 0 && this.transitionTotal > 0) {
+			const progress = 1 - this.transitionRemaining / this.transitionTotal;
+			lineCount = Math.round(this.transitionFromLines + progress * (targetLines - this.transitionFromLines));
+		} else {
+			lineCount = targetLines;
+		}
+
+		const blink = this.isBlinking && !this.doubleBlinkGap
+			&& (this.phase === "face" || this.phase === "full");
+		const lines: string[] = [];
+		if (lineCount >= 1) lines.push(art[0]);
+		if (lineCount >= 2) lines.push(blink ? BLINK_ART[1] : art[1]);
+		if (lineCount >= 3) lines.push(blink ? BLINK_ART[2] : art[2]);
+
+		return { lines, extraPad: this.offset };
+	}
+}