arbiter-ai 1.0.0

package/dist/tui/render.js

@@ -0,0 +1,266 @@
+// TUI rendering logic
+// Handles updating the display with agent outputs and system status
+import { toRoman } from '../state.js';
+/**
+ * Box drawing characters for borders
+ */
+const BOX_CHARS = {
+    topLeft: '\u2554', // ╔
+    topRight: '\u2557', // ╗
+    bottomLeft: '\u255A', // ╚
+    bottomRight: '\u255D', // ╝
+    horizontal: '\u2550', // ═
+    vertical: '\u2551', // ║
+    leftT: '\u2560', // ╠
+    rightT: '\u2563', // ╣
+};
+/**
+ * Progress bar characters
+ */
+const PROGRESS_CHARS = {
+    filled: '\u2588', // █
+    empty: '\u2591', // ░
+};
+/**
+ * Tool indicator character
+ */
+const TOOL_INDICATOR = '\u25C8'; // ◈
+/**
+ * Animation state for loading dots
+ */
+let animationFrame = 0;
+/**
+ * Generates animated dots text based on current animation frame
+ * Cycles through: "Working." -> "Working.." -> "Working..."
+ * @param baseText - The base text to animate (e.g., "Working" or "Waiting for Arbiter")
+ * @returns The text with animated dots appended
+ */
+export function getAnimatedDots(baseText) {
+    const dotCount = (animationFrame % 3) + 1;
+    return baseText + '.'.repeat(dotCount);
+}
+/**
+ * Advances the animation frame for the loading dots
+ * Should be called by an interval timer
+ */
+export function advanceAnimation() {
+    animationFrame = (animationFrame + 1) % 3;
+}
+/**
+ * Resets the animation frame to 0
+ */
+export function resetAnimation() {
+    animationFrame = 0;
+}
+/**
+ * Renders the conversation log to the conversation box
+ * Formats messages with speakers (You:, Arbiter:, Orchestrator I:, etc.)
+ */
+export function renderConversation(elements, state) {
+    const { conversationBox, screen } = elements;
+    const lines = [];
+    // Get effective width for text wrapping
+    const effectiveWidth = Math.max(screen.width - 6, 74);
+    for (const message of state.conversationLog) {
+        // Format speaker label
+        const speakerLabel = formatSpeakerLabel(message.speaker);
+        // Format and wrap the message text
+        const wrappedText = wrapText(message.text, effectiveWidth - speakerLabel.length - 2);
+        const textLines = wrappedText.split('\n');
+        // First line with speaker label
+        lines.push(`  ${speakerLabel} ${textLines[0]}`);
+        // Subsequent lines indented to align with first line
+        const indent = ' '.repeat(speakerLabel.length + 3);
+        for (let i = 1; i < textLines.length; i++) {
+            lines.push(`${indent}${textLines[i]}`);
+        }
+        // Add empty line between messages
+        lines.push('');
+    }
+    // Join lines and add vertical borders
+    const formattedContent = lines
+        .map((line) => {
+        const paddedLine = line.padEnd(effectiveWidth, ' ');
+        return `${BOX_CHARS.vertical}${paddedLine}${BOX_CHARS.vertical}`;
+    })
+        .join('\n');
+    conversationBox.setContent(formattedContent);
+    // Auto-scroll to bottom
+    conversationBox.setScrollPerc(100);
+    screen.render();
+}
+/**
+ * Renders the status bar with context percentages and current tool
+ *
+ * When orchestrator is active:
+ * ║  Arbiter ─────────────────────────────────────────────────── ██░░░░░░░░ 18%    ║
+ * ║  Orchestrator I ──────────────────────────────────────────── ████████░░ 74%    ║
+ * ║  ◈ Edit (12)                                                                   ║
+ *
+ * When no orchestrator (Arbiter speaks to human):
+ * ║  Arbiter ─────────────────────────────────────────────────── ██░░░░░░░░ 18%    ║
+ * ║  Awaiting your command.                                                        ║
+ *
+ * @param waitingState - Optional waiting state to show animated dots
+ */
+export function renderStatus(elements, state, waitingState = 'none') {
+    const { statusBox, screen } = elements;
+    const effectiveWidth = Math.max(screen.width - 2, 78);
+    // Status separator at top
+    const separator = BOX_CHARS.leftT + BOX_CHARS.horizontal.repeat(effectiveWidth) + BOX_CHARS.rightT;
+    // Progress bar width (10 characters for the bar)
+    const barWidth = 10;
+    // Build Arbiter status line
+    const arbiterLabel = 'Arbiter';
+    const arbiterBar = renderProgressBar(state.arbiterContextPercent, barWidth);
+    const arbiterPercent = `${Math.round(state.arbiterContextPercent)}%`.padStart(4);
+    const arbiterDashes = createDashLine(effectiveWidth - arbiterLabel.length - barWidth - arbiterPercent.length - 8);
+    const arbiterLine = `${BOX_CHARS.vertical}  ${arbiterLabel} ${arbiterDashes} ${arbiterBar} ${arbiterPercent}  ${BOX_CHARS.vertical}`;
+    let orchestratorLine;
+    let toolLine;
+    if (state.currentOrchestrator) {
+        // Orchestrator status line
+        const orchLabel = `Orchestrator ${toRoman(state.currentOrchestrator.number)}`;
+        const orchBar = renderProgressBar(state.currentOrchestrator.contextPercent, barWidth);
+        const orchPercent = `${Math.round(state.currentOrchestrator.contextPercent)}%`.padStart(4);
+        const orchDashes = createDashLine(effectiveWidth - orchLabel.length - barWidth - orchPercent.length - 8);
+        orchestratorLine = `${BOX_CHARS.vertical}  ${orchLabel} ${orchDashes} ${orchBar} ${orchPercent}  ${BOX_CHARS.vertical}`;
+        // Tool indicator line
+        if (state.currentOrchestrator.currentTool) {
+            const toolText = `${TOOL_INDICATOR} ${state.currentOrchestrator.currentTool} (${state.currentOrchestrator.toolCallCount})`;
+            const toolPadding = ' '.repeat(effectiveWidth - toolText.length - 2);
+            toolLine = `${BOX_CHARS.vertical}  ${toolText}${toolPadding}${BOX_CHARS.vertical}`;
+        }
+        else if (waitingState === 'orchestrator') {
+            // Show animated dots when waiting for orchestrator response
+            const waitingText = getAnimatedDots('Working');
+            const waitingPadding = ' '.repeat(effectiveWidth - waitingText.length - 2);
+            toolLine = `${BOX_CHARS.vertical}  ${waitingText}${waitingPadding}${BOX_CHARS.vertical}`;
+        }
+        else {
+            const waitingText = 'Working...';
+            const waitingPadding = ' '.repeat(effectiveWidth - waitingText.length - 2);
+            toolLine = `${BOX_CHARS.vertical}  ${waitingText}${waitingPadding}${BOX_CHARS.vertical}`;
+        }
+    }
+    else if (waitingState === 'arbiter') {
+        // Waiting for Arbiter response - show animated dots
+        const waitingText = getAnimatedDots('Waiting for Arbiter');
+        const waitingPadding = ' '.repeat(effectiveWidth - waitingText.length - 2);
+        orchestratorLine = `${BOX_CHARS.vertical}  ${waitingText}${waitingPadding}${BOX_CHARS.vertical}`;
+        toolLine = `${BOX_CHARS.vertical}${' '.repeat(effectiveWidth)}${BOX_CHARS.vertical}`;
+    }
+    else {
+        // No orchestrator - show awaiting message
+        const awaitingText = 'Awaiting your command.';
+        const awaitingPadding = ' '.repeat(effectiveWidth - awaitingText.length - 2);
+        orchestratorLine = `${BOX_CHARS.vertical}  ${awaitingText}${awaitingPadding}${BOX_CHARS.vertical}`;
+        toolLine = `${BOX_CHARS.vertical}${' '.repeat(effectiveWidth)}${BOX_CHARS.vertical}`;
+    }
+    statusBox.setContent(`${separator}\n${arbiterLine}\n${orchestratorLine}\n${toolLine}`);
+    screen.render();
+}
+/**
+ * Creates an ASCII progress bar
+ * @param percent - Current percentage (0-100)
+ * @param width - Total width of the progress bar
+ * @returns Progress bar string like "████████░░"
+ */
+export function renderProgressBar(percent, width) {
+    // Clamp percent between 0 and 100
+    const clampedPercent = Math.max(0, Math.min(100, percent));
+    // Calculate filled width
+    const filledWidth = Math.round((clampedPercent / 100) * width);
+    const emptyWidth = width - filledWidth;
+    // Build progress bar
+    return PROGRESS_CHARS.filled.repeat(filledWidth) + PROGRESS_CHARS.empty.repeat(emptyWidth);
+}
+/**
+ * Formats a speaker label with appropriate styling
+ */
+function formatSpeakerLabel(speaker) {
+    switch (speaker) {
+        case 'human':
+            return '{bold}You:{/bold}';
+        case 'arbiter':
+            return '{bold}{yellow-fg}Arbiter:{/yellow-fg}{/bold}';
+        default:
+            // Orchestrator labels come through as-is (e.g., "Orchestrator I")
+            if (speaker.startsWith('Orchestrator')) {
+                return `{bold}{cyan-fg}${speaker}:{/cyan-fg}{/bold}`;
+            }
+            return `{bold}${speaker}:{/bold}`;
+    }
+}
+/**
+ * Wraps text to fit within a specified width
+ */
+function wrapText(text, maxWidth) {
+    if (maxWidth <= 0) {
+        return text;
+    }
+    const words = text.split(' ');
+    const lines = [];
+    let currentLine = '';
+    for (const word of words) {
+        // Handle words that are longer than maxWidth
+        if (word.length > maxWidth) {
+            // If there's content in the current line, push it first
+            if (currentLine) {
+                lines.push(currentLine.trim());
+                currentLine = '';
+            }
+            // Break the long word
+            let remaining = word;
+            while (remaining.length > maxWidth) {
+                lines.push(remaining.substring(0, maxWidth));
+                remaining = remaining.substring(maxWidth);
+            }
+            currentLine = `${remaining} `;
+            continue;
+        }
+        // Check if adding this word would exceed the limit
+        if (currentLine.length + word.length + 1 > maxWidth) {
+            lines.push(currentLine.trim());
+            currentLine = `${word} `;
+        }
+        else {
+            currentLine += `${word} `;
+        }
+    }
+    // Add remaining content
+    if (currentLine.trim()) {
+        lines.push(currentLine.trim());
+    }
+    return lines.join('\n');
+}
+/**
+ * Creates a dash line for status bar alignment
+ * Uses em-dash (─) for cleaner appearance
+ */
+function createDashLine(length) {
+    const dashChar = '\u2500'; // ─
+    return dashChar.repeat(Math.max(0, length));
+}
+/**
+ * Renders the input area with prompt
+ */
+export function renderInputArea(elements) {
+    const { screen } = elements;
+    const effectiveWidth = Math.max(screen.width - 2, 78);
+    // Input separator and prompt are handled by the layout
+    // This function can be used for additional input area styling if needed
+    // Create input separator
+    const _inputSeparator = BOX_CHARS.leftT + BOX_CHARS.horizontal.repeat(effectiveWidth) + BOX_CHARS.rightT;
+    // The inputBox already has its own styling from layout
+    // We can prepend a separator to the status box if needed
+    screen.render();
+}
+/**
+ * Updates the entire display
+ */
+export function renderAll(elements, state) {
+    renderConversation(elements, state);
+    renderStatus(elements, state);
+    elements.screen.render();
+}

package/dist/tui/scene.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Scene state and composition module for the Arbiter TUI
+ *
+ * Manages scene state and creates tile grids for rendering the wizard council scene.
+ * The scene shows a human, the arbiter, a spellbook, a campfire, and demons.
+ */
+import { type Tileset } from './tileset.js';
+/**
+ * State for a single hop animation at a position
+ * Each hop = 500ms (250ms up + 250ms down)
+ */
+export interface HopState {
+    remaining: number;
+    frameInHop: 0 | 1;
+}
+/**
+ * Scene state describing positions and counts of all scene elements
+ */
+export interface SceneState {
+    arbiterPos: -1 | 0 | 1 | 2;
+    demonCount: number;
+    focusTarget: 'human' | 'arbiter' | 'demon' | null;
+    selectedCharacter: number;
+    humanCol: number;
+    activeHops: Map<string, HopState>;
+    bubbleVisible: boolean;
+    showSpellbook: boolean;
+    chatBubbleTarget: 'human' | 'arbiter' | 'conjuring' | null;
+    alertTarget: 'human' | 'arbiter' | 'conjuring' | null;
+    scrollVisible: boolean;
+}
+/**
+ * Tile specification - either a simple tile index or an object with mirroring
+ */
+export type TileSpec = number | {
+    tile: number;
+    mirrored: boolean;
+};
+/**
+ * Create initial scene state with defaults
+ */
+export declare function createInitialSceneState(): SceneState;
+/**
+ * Create a 7x6 grid of tile specifications based on scene state
+ *
+ * Scene Layout:
+ * - Row 0-1: Trees on edges (col 0 and 6), grass elsewhere
+ * - Row 2: Human at col 1, Arbiter at col 2-4 (based on arbiterPos), Cauldron at col 5, tree at col 6
+ * - Row 3: Tree at col 0, grass, campfire at col 5, tree at col 6
+ * - Row 4-5: Trees at col 0 and 6, grass elsewhere
+ * - Demons spawn around campfire at col 5-6, rows 1-3
+ * - Smoke bubbles appear above cauldron when working
+ * - Spellbook appears to the left of arbiter when at position 2
+ */
+export declare function createScene(state: SceneState): TileSpec[][];
+/**
+ * Render the scene to an ANSI string
+ *
+ * @param tileset - The loaded tileset
+ * @param scene - The tile grid from createScene
+ * @param activeHops - Map of "row,col" -> HopState for positions that should hop
+ * @param sceneState - Optional scene state for chat bubble rendering
+ */
+export declare function renderScene(tileset: Tileset, scene: TileSpec[][], activeHops?: Map<string, HopState>, sceneState?: SceneState): string;

package/dist/tui/scene.js

@@ -0,0 +1,366 @@
+/**
+ * Scene state and composition module for the Arbiter TUI
+ *
+ * Manages scene state and creates tile grids for rendering the wizard council scene.
+ * The scene shows a human, the arbiter, a spellbook, a campfire, and demons.
+ */
+import { CHAR_HEIGHT, compositeQuarterTile, compositeTiles, extractQuarterTile, extractTile, mirrorTile, renderTile, TILE, } from './tileset.js';
+// ============================================================================
+// Constants
+// ============================================================================
+const SCENE_WIDTH = 7;
+const SCENE_HEIGHT = 6;
+// Demon spawn positions around the campfire (order matters for spawning)
+const DEMON_POSITIONS = [
+    { row: 2, col: 6, tile: TILE.DEMON_1 }, // right of fire (first)
+    { row: 1, col: 6, tile: TILE.DEMON_2 }, // above-right
+    { row: 3, col: 6, tile: TILE.DEMON_3 }, // below-right
+    { row: 1, col: 5, tile: TILE.DEMON_4 }, // above fire
+    { row: 3, col: 5, tile: TILE.DEMON_5 }, // below fire
+];
+/**
+ * Get a varied grass tile based on position for visual variety
+ * Returns ~30% sparse grass, ~70% regular grass using a deterministic pattern
+ */
+function getGrassTile(row, col) {
+    // Use a simple pattern based on position for variety
+    // This creates a natural-looking distribution of grass types
+    const pattern = (row * 3 + col * 7) % 10;
+    if (pattern < 3)
+        return TILE.GRASS_SPARSE;
+    return TILE.GRASS;
+}
+// ============================================================================
+// Tile Render Cache
+// ============================================================================
+const tileCache = new Map();
+/**
+ * Generate cache key for a tile render
+ */
+function getCacheKey(tileIndex, mirrored) {
+    return `${tileIndex}:${mirrored ? 'M' : 'N'}`;
+}
+/**
+ * Get or create a cached tile render
+ */
+function getTileRender(tileset, grassPixels, tileIndex, mirrored = false) {
+    const key = getCacheKey(tileIndex, mirrored);
+    if (tileCache.has(key)) {
+        return tileCache.get(key);
+    }
+    let pixels = extractTile(tileset, tileIndex);
+    // Composite tiles >= 80 on grass (characters, objects, etc.)
+    if (tileIndex >= 80) {
+        pixels = compositeTiles(pixels, grassPixels, 1);
+    }
+    if (mirrored) {
+        pixels = mirrorTile(pixels);
+    }
+    const rendered = renderTile(pixels);
+    tileCache.set(key, rendered);
+    return rendered;
+}
+// ============================================================================
+// Factory Function
+// ============================================================================
+/**
+ * Create initial scene state with defaults
+ */
+export function createInitialSceneState() {
+    return {
+        arbiterPos: 2, // Start by fire (row 3), walks to scroll when first message ready
+        demonCount: 0,
+        focusTarget: null,
+        selectedCharacter: TILE.HUMAN_1,
+        humanCol: 1, // Default position (after entry animation)
+        // Animation state
+        activeHops: new Map(),
+        bubbleVisible: false,
+        showSpellbook: false,
+        // Chat bubble
+        chatBubbleTarget: null,
+        // Alert/exclamation indicator
+        alertTarget: null,
+        // Scroll of requirements
+        scrollVisible: false,
+    };
+}
+// ============================================================================
+// Scene Creation
+// ============================================================================
+/**
+ * Create a 7x6 grid of tile specifications based on scene state
+ *
+ * Scene Layout:
+ * - Row 0-1: Trees on edges (col 0 and 6), grass elsewhere
+ * - Row 2: Human at col 1, Arbiter at col 2-4 (based on arbiterPos), Cauldron at col 5, tree at col 6
+ * - Row 3: Tree at col 0, grass, campfire at col 5, tree at col 6
+ * - Row 4-5: Trees at col 0 and 6, grass elsewhere
+ * - Demons spawn around campfire at col 5-6, rows 1-3
+ * - Smoke bubbles appear above cauldron when working
+ * - Spellbook appears to the left of arbiter when at position 2
+ */
+export function createScene(state) {
+    const { arbiterPos, demonCount, selectedCharacter, humanCol, bubbleVisible, showSpellbook, scrollVisible, } = state;
+    // arbiterPos -1 means off-screen (not visible)
+    const arbiterVisible = arbiterPos >= 0;
+    // Position mapping:
+    // Pos 2: row 3, col 4 (by fire - starting position)
+    // Pos 1: row 2, col 4 (by cauldron)
+    // Pos 0: row 2, col 3 (by scroll - final position)
+    let arbiterCol = -1;
+    let arbiterRow = 2;
+    if (arbiterVisible) {
+        switch (arbiterPos) {
+            case 0:
+                arbiterCol = 3;
+                arbiterRow = 2;
+                break;
+            case 1:
+                arbiterCol = 4;
+                arbiterRow = 2;
+                break;
+            case 2:
+                arbiterCol = 4;
+                arbiterRow = 3;
+                break;
+        }
+    }
+    const scene = [];
+    for (let row = 0; row < SCENE_HEIGHT; row++) {
+        const sceneRow = [];
+        for (let col = 0; col < SCENE_WIDTH; col++) {
+            let tile = getGrassTile(row, col);
+            // Trees on left edge (col 0), except row 2 which is the path entrance
+            if (col === 0) {
+                tile = row === 2 ? TILE.GRASS_SPARSE : TILE.PINE_TREE;
+            }
+            // Bare trees at specific positions on col 1
+            if (col === 1 && (row === 0 || row === 4)) {
+                tile = TILE.BARE_TREE;
+            }
+            // Trees on right edge (col 6)
+            if (col === 6 && (row === 0 || row === 4 || row === 5)) {
+                tile = TILE.PINE_TREE;
+            }
+            // Human character on row 2 at humanCol position
+            if (row === 2 && col === humanCol && humanCol >= 0 && humanCol < SCENE_WIDTH) {
+                tile = selectedCharacter;
+            }
+            // Scroll of requirements (row 2, col 2) - between human and arbiter
+            if (scrollVisible && row === 2 && col === 2) {
+                tile = TILE.SCROLL;
+            }
+            // Spellbook at row 4, col 4 (one down and left from campfire)
+            // Shows when explicitly set (during arbiter's working position)
+            if (showSpellbook && row === 4 && col === 4) {
+                tile = TILE.SPELLBOOK;
+            }
+            // Cauldron (row 2, col 5)
+            if (row === 2 && col === 5) {
+                tile = TILE.CAULDRON;
+            }
+            // Smoke/bubbles above cauldron when bubbleVisible is true
+            if (bubbleVisible && row === 1 && col === 5) {
+                tile = TILE.SMOKE;
+            }
+            // Campfire (row 3, col 5)
+            if (row === 3 && col === 5) {
+                tile = TILE.CAMPFIRE;
+            }
+            // Arbiter - only draw if visible (arbiterPos >= 0)
+            if (arbiterVisible && row === arbiterRow && col === arbiterCol) {
+                tile = TILE.ARBITER;
+            }
+            // Demons based on count (spawn in order)
+            for (let i = 0; i < Math.min(demonCount, DEMON_POSITIONS.length); i++) {
+                const dp = DEMON_POSITIONS[i];
+                if (row === dp.row && col === dp.col) {
+                    tile = dp.tile;
+                }
+            }
+            sceneRow.push(tile);
+        }
+        scene.push(sceneRow);
+    }
+    return scene;
+}
+// ============================================================================
+// Scene Rendering
+// ============================================================================
+/**
+ * Get the row,col position for a chat bubble target
+ */
+function getChatBubblePosition(state, target) {
+    switch (target) {
+        case 'human':
+            return { row: 2, col: state.humanCol };
+        case 'arbiter': {
+            const pos = state.arbiterPos;
+            switch (pos) {
+                case 0:
+                    return { row: 2, col: 3 }; // By scroll
+                case 1:
+                    return { row: 2, col: 4 }; // By cauldron
+                case 2:
+                    return { row: 3, col: 4 }; // By fire
+                default:
+                    return { row: 2, col: 3 };
+            }
+        }
+        case 'conjuring':
+            // First demon position
+            return { row: 2, col: 6 };
+    }
+}
+// Cache for the chat bubble quarter tile (extracted once, reused)
+let chatBubbleQuarterCache = null;
+/**
+ * Get or create the cached chat bubble quarter tile
+ */
+function getChatBubbleQuarter(tileset) {
+    if (!chatBubbleQuarterCache) {
+        const quartersTile = extractTile(tileset, TILE.CHAT_BUBBLE_QUARTERS);
+        chatBubbleQuarterCache = extractQuarterTile(quartersTile, 'top-right');
+    }
+    return chatBubbleQuarterCache;
+}
+// Cache for the alert/exclamation quarter tile (extracted once, reused)
+let alertQuarterCache = null;
+/**
+ * Get or create the cached alert/exclamation quarter tile
+ */
+function getAlertQuarter(tileset) {
+    if (!alertQuarterCache) {
+        const quartersTile = extractTile(tileset, TILE.ALERT_QUARTERS);
+        alertQuarterCache = extractQuarterTile(quartersTile, 'top-left');
+    }
+    return alertQuarterCache;
+}
+/**
+ * Render the scene to an ANSI string
+ *
+ * @param tileset - The loaded tileset
+ * @param scene - The tile grid from createScene
+ * @param activeHops - Map of "row,col" -> HopState for positions that should hop
+ * @param sceneState - Optional scene state for chat bubble rendering
+ */
+export function renderScene(tileset, scene, activeHops = new Map(), sceneState) {
+    // Get grass pixels for compositing
+    const grassPixels = extractTile(tileset, TILE.GRASS);
+    // Determine chat bubble position if target is set
+    let bubbleRow = -1;
+    let bubbleCol = -1;
+    if (sceneState?.chatBubbleTarget) {
+        const pos = getChatBubblePosition(sceneState, sceneState.chatBubbleTarget);
+        bubbleRow = pos.row;
+        bubbleCol = pos.col;
+    }
+    // Determine alert/exclamation position if target is set
+    let alertRow = -1;
+    let alertCol = -1;
+    if (sceneState?.alertTarget) {
+        const pos = getChatBubblePosition(sceneState, sceneState.alertTarget);
+        alertRow = pos.row;
+        alertCol = pos.col;
+    }
+    const renderedTiles = [];
+    for (let row = 0; row < scene.length; row++) {
+        const renderedRow = [];
+        for (let col = 0; col < scene[row].length; col++) {
+            const tileSpec = scene[row][col];
+            let tileIndex;
+            let mirrored = false;
+            if (typeof tileSpec === 'number') {
+                tileIndex = tileSpec;
+            }
+            else {
+                tileIndex = tileSpec.tile;
+                mirrored = tileSpec.mirrored;
+            }
+            // Check if this position needs an overlay (chat bubble or alert)
+            const needsBubble = row === bubbleRow && col === bubbleCol;
+            const needsAlert = row === alertRow && col === alertCol;
+            if (needsBubble || needsAlert) {
+                // Render without cache, adding the overlay
+                let pixels = extractTile(tileset, tileIndex);
+                // Composite on grass if needed
+                if (tileIndex >= 80) {
+                    pixels = compositeTiles(pixels, grassPixels, 1);
+                }
+                if (mirrored) {
+                    pixels = mirrorTile(pixels);
+                }
+                // Add chat bubble to top-right corner
+                if (needsBubble) {
+                    const bubbleQuarter = getChatBubbleQuarter(tileset);
+                    pixels = compositeQuarterTile(pixels, bubbleQuarter, 'top-right', 1);
+                }
+                // Add alert/exclamation to top-left corner
+                if (needsAlert) {
+                    const alertQuarter = getAlertQuarter(tileset);
+                    pixels = compositeQuarterTile(pixels, alertQuarter, 'top-left', 1);
+                }
+                renderedRow.push(renderTile(pixels));
+            }
+            else {
+                // Use cached render
+                renderedRow.push(getTileRender(tileset, grassPixels, tileIndex, mirrored));
+            }
+        }
+        renderedTiles.push(renderedRow);
+    }
+    // Build output string
+    // Hop detection now uses activeHops map - check if position is hopping and in "up" frame
+    // When hopping, we need to shift the hopping tile up by 1 row
+    // This means: at the row above, we show the bottom row of the hopping tile
+    // and at the tile's normal position, we show rows shifted up
+    const lines = [];
+    for (let tileRow = 0; tileRow < scene.length; tileRow++) {
+        for (let charRow = 0; charRow < CHAR_HEIGHT; charRow++) {
+            let line = '';
+            for (let tileCol = 0; tileCol < scene[tileRow].length; tileCol++) {
+                // Check if this position is hopping (and in "up" frame)
+                const hopKey = `${tileRow},${tileCol}`;
+                const hopState = activeHops.get(hopKey);
+                const isHoppingTile = hopState && hopState.frameInHop === 0;
+                // Check if tile above is hopping (for the overflow effect)
+                const hopKeyBelow = `${tileRow + 1},${tileCol}`;
+                const hopStateBelow = activeHops.get(hopKeyBelow);
+                const isTileAboveHopping = hopStateBelow && hopStateBelow.frameInHop === 0;
+                if (isHoppingTile) {
+                    // For the hopping tile, show the row below (shifted up)
+                    // If charRow is 0, we show nothing special (already handled by tile above)
+                    // Otherwise show charRow - 1 if we're hopping, but we need to handle the overlap
+                    if (charRow === 0) {
+                        // First char row of hopping tile shows second row of the tile
+                        line += renderedTiles[tileRow][tileCol][1];
+                    }
+                    else if (charRow === CHAR_HEIGHT - 1) {
+                        // Last char row shows grass (the tile has moved up)
+                        line += renderedTiles[tileRow][tileCol][charRow]; // Actually show grass from tile
+                    }
+                    else {
+                        // Show the next row down (shifted up by 1)
+                        line += renderedTiles[tileRow][tileCol][charRow + 1];
+                    }
+                }
+                else if (isTileAboveHopping) {
+                    // For the tile above the hopping tile, the last row shows the first row of the hopping tile
+                    if (charRow === CHAR_HEIGHT - 1) {
+                        line += renderedTiles[tileRow + 1][tileCol][0];
+                    }
+                    else {
+                        line += renderedTiles[tileRow][tileCol][charRow];
+                    }
+                }
+                else {
+                    line += renderedTiles[tileRow][tileCol][charRow];
+                }
+            }
+            lines.push(line);
+        }
+    }
+    // Join with newlines (no trailing newline to prevent extra line causing flicker)
+    return lines.join('\n');
+}