soja-cli 1.4.0

package/dist/ui/input/KeyProvider.js

@@ -0,0 +1,101 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useApp, useInput, useStdout } from 'ink';
+import { createContext, useCallback, useContext, useEffect, useLayoutEffect, useRef, useState } from 'react';
+import { KeyDispatcher, Layer } from './dispatcher.js';
+import { MOUSE_OFF, MOUSE_ON, MouseDispatcher, parseMouse, rectOf } from './mouse.js';
+const InputContext = createContext(null);
+/**
+ * All input goes through here: keys to the layered key dispatcher, mouse
+ * reports to the clickable regions. A mouse report never reaches a key handler.
+ */
+export function KeyProvider({ children, mouse = false }) {
+    const [context] = useState(() => ({ keys: new KeyDispatcher(), mouse: new MouseDispatcher(), mouseEnabled: mouse }));
+    const { stdout } = useStdout();
+    useInput((input, key) => {
+        const event = parseMouse(input);
+        if (event)
+            context.mouse.dispatch(event);
+        else
+            context.keys.dispatch(input, key);
+    });
+    useEffect(() => {
+        if (!mouse)
+            return;
+        stdout.write(MOUSE_ON);
+        // Whatever way SOJA ends, the terminal must stop sending mouse reports.
+        const off = () => stdout.write(MOUSE_OFF);
+        process.once('exit', off);
+        return () => {
+            off();
+            process.off('exit', off);
+        };
+    }, [mouse, stdout]);
+    return _jsx(InputContext.Provider, { value: context, children: children });
+}
+function useInputContext() {
+    const context = useContext(InputContext);
+    if (!context)
+        throw new Error('Input hooks must be used inside <KeyProvider>');
+    return context;
+}
+/**
+ * Registers `handler` on a layer while `active`. The latest handler is always used.
+ * Layout effects register during the commit itself, so a key typed right after
+ * opening an overlay reaches the overlay, not the shortcut underneath it.
+ */
+export function useKeys(layer, handler, active = true) {
+    const { keys } = useInputContext();
+    const latest = useRef(handler);
+    useLayoutEffect(() => {
+        latest.current = handler;
+    });
+    useLayoutEffect(() => {
+        if (!active)
+            return;
+        return keys.register(layer, (input, key) => latest.current(input, key));
+    }, [keys, layer, active]);
+}
+/**
+ * Makes the element behind `ref` react to clicks and the wheel while `active`.
+ * Its position is read from the layout when the event arrives, so it follows
+ * scrolling and resizing.
+ */
+export function useClickable(ref, target, options = {}) {
+    const { mouse } = useInputContext();
+    const latest = useRef(target);
+    useLayoutEffect(() => {
+        latest.current = target;
+    });
+    const layer = options.layer ?? Layer.screen;
+    const active = options.active ?? true;
+    useLayoutEffect(() => {
+        if (!active)
+            return;
+        return mouse.register(layer, () => rectOf(ref.current), () => latest.current);
+    }, [mouse, layer, active, ref]);
+}
+/**
+ * Hands the terminal to another program (an editor, Git asking for a
+ * password) and takes it back. The mouse is switched off meanwhile, so the
+ * program does not receive mouse reports as typed text.
+ */
+export function useExternalTerminal() {
+    const { suspendTerminal } = useApp();
+    const { stdout } = useStdout();
+    const { mouseEnabled } = useInputContext();
+    return useCallback(async (work) => {
+        let result;
+        if (mouseEnabled)
+            stdout.write(MOUSE_OFF);
+        try {
+            await suspendTerminal(async () => {
+                result = await work();
+            });
+        }
+        finally {
+            if (mouseEnabled)
+                stdout.write(MOUSE_ON);
+        }
+        return result;
+    }, [suspendTerminal, stdout, mouseEnabled]);
+}

package/dist/ui/input/dispatcher.js

@@ -0,0 +1,26 @@
+/**
+ * Who gets a key first. Text fields beat overlays, overlays beat screens,
+ * screens beat global shortcuts. That ordering is what lets `p` mean
+ * "priority" in a task and "projects" everywhere else, and keeps Esc
+ * predictable: the topmost thing always closes first.
+ */
+export const Layer = { global: 0, screen: 10, overlay: 20, input: 30 };
+export class KeyDispatcher {
+    entries = [];
+    counter = 0;
+    register(layer, handler) {
+        const entry = { layer, order: (this.counter += 1), handler };
+        this.entries.push(entry);
+        return () => {
+            this.entries = this.entries.filter((candidate) => candidate !== entry);
+        };
+    }
+    dispatch(input, key) {
+        const ordered = [...this.entries].sort((a, b) => b.layer - a.layer || b.order - a.order);
+        for (const entry of ordered) {
+            if (entry.handler(input, key) === true)
+                return true;
+        }
+        return false;
+    }
+}

package/dist/ui/input/list-navigation.js

@@ -0,0 +1,38 @@
+/**
+ * Vim-style movement over a list of `count` items shown `height` at a time.
+ * Returns the new state, or `null` when the key is not a movement key.
+ * `vim` is off inside text inputs, where j/k are letters.
+ */
+export function moveInList(state, input, key, count, height, vim = true) {
+    // Letters only count as vim motions when typed bare: ctrl+k is not k.
+    const letter = vim && !key.ctrl && !key.meta ? input : '';
+    let index;
+    if (key.downArrow || letter === 'j' || (key.ctrl && input === 'n'))
+        index = state.index + 1;
+    else if (key.upArrow || letter === 'k' || (key.ctrl && input === 'p'))
+        index = state.index - 1;
+    else if (key.pageDown || (key.ctrl && input === 'd'))
+        index = state.index + Math.max(1, Math.floor(height / 2));
+    else if (key.pageUp || (key.ctrl && input === 'u'))
+        index = state.index - Math.max(1, Math.floor(height / 2));
+    else if (letter === 'g' || key.home)
+        index = 0;
+    else if (letter === 'G' || key.end)
+        index = count - 1;
+    else
+        return null;
+    return clampList({ index, offset: state.offset }, count, height);
+}
+/** Keeps the selection inside the list and the viewport around the selection. */
+export function clampList(state, count, height) {
+    if (count <= 0)
+        return { index: 0, offset: 0 };
+    const visible = Math.max(1, height);
+    const index = Math.max(0, Math.min(count - 1, state.index));
+    let offset = Math.max(0, Math.min(state.offset, Math.max(0, count - visible)));
+    if (index < offset)
+        offset = index;
+    if (index >= offset + visible)
+        offset = index - visible + 1;
+    return { index, offset };
+}

package/dist/ui/input/mouse.js

@@ -0,0 +1,78 @@
+/**
+ * SGR mouse reports (`ESC [ < b ; x ; y M|m`). Ink strips the ESC and hands
+ * the rest to `useInput`, so this recognizes them there before they could be
+ * mistaken for keys.
+ */
+const SGR = /^\[<(\d+);(\d+);(\d+)([Mm])$/;
+export function parseMouse(input) {
+    const match = SGR.exec(input);
+    if (!match)
+        return null;
+    const code = Number(match[1]);
+    const x = Number(match[2]) - 1;
+    const y = Number(match[3]) - 1;
+    if (code & 64)
+        return { kind: (code & 1) === 1 ? 'wheel-down' : 'wheel-up', button: 'none', x, y };
+    const button = ['left', 'middle', 'right'][code & 3] ?? 'none';
+    return { kind: match[4] === 'M' ? 'press' : 'release', button, x, y };
+}
+/** Terminal sequences: report presses, releases and the wheel, in SGR format. */
+export const MOUSE_ON = '\u001b[?1000h\u001b[?1006h';
+export const MOUSE_OFF = '\u001b[?1000l\u001b[?1006l';
+/** Where an Ink element is on screen: its layout offsets summed up to the root. */
+export function rectOf(element) {
+    const layout = element?.yogaNode?.getComputedLayout();
+    if (!element || !layout)
+        return null;
+    let x = layout.left;
+    let y = layout.top;
+    for (let parent = element.parentNode; parent; parent = parent.parentNode) {
+        const offset = parent.yogaNode?.getComputedLayout();
+        if (offset) {
+            x += offset.left;
+            y += offset.top;
+        }
+    }
+    return { x: Math.round(x), y: Math.round(y), width: Math.round(layout.width), height: Math.round(layout.height) };
+}
+const contains = (rect, event) => event.x >= rect.x && event.x < rect.x + rect.width && event.y >= rect.y && event.y < rect.y + rect.height;
+/**
+ * Clickable regions, by layer like the keyboard: an open window catches
+ * clicks before the screen under it. Within the top layer that contains the
+ * point, the smallest region wins (a button inside a panel).
+ */
+export class MouseDispatcher {
+    regions = [];
+    counter = 0;
+    register(layer, rect, target) {
+        const region = { layer, order: (this.counter += 1), rect, target };
+        this.regions.push(region);
+        return () => {
+            this.regions = this.regions.filter((candidate) => candidate !== region);
+        };
+    }
+    dispatch(event) {
+        // Clicks act on press, like most terminal apps; releases are ignored.
+        if (event.kind === 'release')
+            return false;
+        const hits = this.regions
+            .map((region) => ({ region, rect: region.rect() }))
+            .filter((hit) => hit.rect !== null && contains(hit.rect, event));
+        const topLayer = Math.max(...hits.map((hit) => hit.region.layer));
+        const candidates = hits
+            .filter((hit) => hit.region.layer === topLayer)
+            .sort((a, b) => a.rect.width * a.rect.height - b.rect.width * b.rect.height || b.region.order - a.region.order);
+        for (const { region, rect } of candidates) {
+            const target = region.target();
+            if (event.kind === 'press' && event.button === 'left' && target.onClick) {
+                target.onClick(event, rect);
+                return true;
+            }
+            if ((event.kind === 'wheel-up' || event.kind === 'wheel-down') && target.onWheel) {
+                target.onWheel(event.kind === 'wheel-down' ? 1 : -1, event);
+                return true;
+            }
+        }
+        return false;
+    }
+}

package/dist/ui/input/text-editing.js

@@ -0,0 +1,62 @@
+/**
+ * Pure line-editing rules for text fields (readline-style). Returns the new
+ * state, or `null` when the key is not an editing key, so the owner can use
+ * it (Enter, Esc, Tab, arrows up/down).
+ */
+export function editText(state, input, key) {
+    const { value, cursor } = state;
+    const at = (nextValue, nextCursor) => ({
+        value: nextValue,
+        cursor: Math.max(0, Math.min(nextValue.length, nextCursor)),
+    });
+    if (key.return || key.escape || key.tab || key.upArrow || key.downArrow || key.pageUp || key.pageDown)
+        return null;
+    if (key.leftArrow)
+        return at(value, key.ctrl || key.meta ? wordStart(value, cursor) : cursor - 1);
+    if (key.rightArrow)
+        return at(value, key.ctrl || key.meta ? wordEnd(value, cursor) : cursor + 1);
+    if (key.home || (key.ctrl && input === 'a'))
+        return at(value, 0);
+    if (key.end || (key.ctrl && input === 'e'))
+        return at(value, value.length);
+    if (key.backspace) {
+        if (key.meta) {
+            const start = wordStart(value, cursor);
+            return at(value.slice(0, start) + value.slice(cursor), start);
+        }
+        return cursor === 0 ? state : at(value.slice(0, cursor - 1) + value.slice(cursor), cursor - 1);
+    }
+    if (key.delete)
+        return at(value.slice(0, cursor) + value.slice(cursor + 1), cursor);
+    if (key.ctrl && input === 'u')
+        return at(value.slice(cursor), 0);
+    if (key.ctrl && input === 'k')
+        return at(value.slice(0, cursor), cursor);
+    if (key.ctrl && input === 'w') {
+        const start = wordStart(value, cursor);
+        return at(value.slice(0, start) + value.slice(cursor), start);
+    }
+    if (key.ctrl || key.meta)
+        return null;
+    // Printable text, including pastes. Newlines and control characters are dropped.
+    const text = input.replace(/[\r\n]+/g, ' ').replace(/\p{Cc}/gu, '');
+    if (!text)
+        return null;
+    return at(value.slice(0, cursor) + text + value.slice(cursor), cursor + text.length);
+}
+function wordStart(value, cursor) {
+    let index = cursor;
+    while (index > 0 && value[index - 1] === ' ')
+        index -= 1;
+    while (index > 0 && value[index - 1] !== ' ')
+        index -= 1;
+    return index;
+}
+function wordEnd(value, cursor) {
+    let index = cursor;
+    while (index < value.length && value[index] === ' ')
+        index += 1;
+    while (index < value.length && value[index] !== ' ')
+        index += 1;
+    return index;
+}

package/dist/ui/kit/Badge.js

@@ -0,0 +1,8 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Text } from 'ink';
+import { toneColors } from '../theme/theme.js';
+/** A filled label: ` IN PROGRESS `. The soft background keeps it readable in light and dark terminals. */
+export function Badge({ tone, children, bold = false }) {
+    const { fg, bg } = toneColors(tone);
+    return (_jsx(Text, { backgroundColor: bg, color: fg, bold: bold, children: ` ${children} ` }));
+}

package/dist/ui/kit/Button.js

@@ -0,0 +1,13 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Text } from 'ink';
+import { palette, toneColors } from '../theme/theme.js';
+import { Layer } from '../input/dispatcher.js';
+import { Clickable } from './Clickable.js';
+/** `[ Delete ]`: a clickable action in a window. `primary` is filled; `focused` shows which one Enter picks. */
+export function Button({ label, onPress, variant = 'default', tone, focused = false, layer = Layer.overlay, }) {
+    const colors = tone ? toneColors(tone) : null;
+    const filled = variant === 'primary' || focused;
+    const background = filled ? (colors?.fg ?? palette.accent) : palette.neutralSoft;
+    const foreground = filled ? palette.onAccent : (colors?.fg ?? palette.text);
+    return (_jsx(Clickable, { onClick: onPress, layer: layer, children: _jsx(Text, { backgroundColor: background, color: foreground, bold: filled, children: `  ${label}  ` }) }));
+}

package/dist/ui/kit/Clickable.js

@@ -0,0 +1,14 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Box } from 'ink';
+import { useRef } from 'react';
+import { Layer } from '../input/dispatcher.js';
+import { useClickable } from '../input/KeyProvider.js';
+/** Wraps anything that reacts to the mouse. Inactive screens (hidden or under a window) ignore it. */
+export function Clickable({ onClick, onWheel, layer = Layer.screen, active = true, children, ...box }) {
+    const ref = useRef(null);
+    useClickable(ref, {
+        ...(onClick ? { onClick } : {}),
+        ...(onWheel ? { onWheel: (direction) => onWheel(direction) } : {}),
+    }, { layer, active: active && Boolean(onClick || onWheel) });
+    return (_jsx(Box, { ref: ref, ...box, children: children }));
+}

package/dist/ui/kit/Gauge.js

@@ -0,0 +1,9 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Text } from 'ink';
+import { palette, symbols } from '../theme/theme.js';
+/** A thin progress bar: `████░░░░ 50%`. */
+export function Gauge({ value, total, width = 10, color = palette.accent, showPercent = true }) {
+    const ratio = total > 0 ? Math.max(0, Math.min(1, value / total)) : 0;
+    const filled = Math.round(ratio * width);
+    return (_jsxs(Text, { children: [_jsx(Text, { color: color, children: symbols.full.repeat(filled) }), _jsx(Text, { color: palette.border, children: symbols.shade.repeat(width - filled) }), showPercent ? _jsx(Text, { color: palette.muted, children: ` ${String(Math.round(ratio * 100)).padStart(3)}%` }) : null] }));
+}

package/dist/ui/kit/Keycap.js

@@ -0,0 +1,7 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Text } from 'ink';
+import { palette } from '../theme/theme.js';
+/** A key drawn like a keyboard key, followed by what it does: `[ enter ] open`. */
+export function Keycap({ keys, label }) {
+    return (_jsxs(Text, { children: [_jsx(Text, { backgroundColor: palette.neutralSoft, color: palette.text, bold: true, children: ` ${keys} ` }), label ? _jsx(Text, { color: palette.muted, children: ` ${label}` }) : null] }));
+}

package/dist/ui/kit/Panel.js

@@ -0,0 +1,30 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { Box, Text } from 'ink';
+import { useRef } from 'react';
+import { useMeasure } from '../hooks/use-measure.js';
+import { useTerminalSize } from '../hooks/use-terminal-size.js';
+import { palette } from '../theme/theme.js';
+/**
+ * A rounded box with its title in the border, the basic block of every
+ * screen. The top border is drawn by hand so the title can sit in it.
+ */
+export function Panel({ title, aside, focused = false, width, height, flexGrow, flexShrink, backgroundColor, paddingX = 1, children }) {
+    const ref = useRef(null);
+    // Re-render on resize so the drawn border follows the new width.
+    useTerminalSize();
+    const { width: measured } = useMeasure(ref);
+    const border = focused ? palette.borderFocus : palette.border;
+    return (_jsxs(Box, { ref: ref, flexDirection: "column", ...(width !== undefined ? { width } : {}), ...(height !== undefined ? { height } : {}), ...(flexGrow !== undefined ? { flexGrow } : {}), ...(flexShrink !== undefined ? { flexShrink } : {}), ...(backgroundColor ? { backgroundColor } : {}), children: [_jsx(Box, { width: "100%", height: 1, overflow: "hidden", flexShrink: 0, children: _jsx(TopBorder, { width: typeof width === 'number' ? width : measured, title: title, aside: aside, color: border, focused: focused, backgroundColor: backgroundColor }) }), _jsx(Box, { flexDirection: "column", flexGrow: 1, ...(height !== undefined ? { height: Math.max(1, height - 1) } : {}), borderStyle: "round", borderTop: false, borderColor: border, paddingX: paddingX, overflow: "hidden", ...(backgroundColor ? { borderBottomBackgroundColor: backgroundColor, borderLeftBackgroundColor: backgroundColor, borderRightBackgroundColor: backgroundColor } : {}), children: _jsx(Box, { flexDirection: "column", flexShrink: 0, flexGrow: 1, children: children }) })] }));
+}
+function TopBorder({ width, title, aside, color, focused, backgroundColor, }) {
+    const inner = Math.max(0, width - 2);
+    const left = title ? ` ${title} ` : '';
+    const right = aside ? ` ${aside} ` : '';
+    // Keep "─" on both sides of the title; drop the aside first when narrow.
+    const fitsAside = left.length + right.length + 3 <= inner;
+    const shownRight = fitsAside ? right : '';
+    const shownLeft = left.length + 2 > inner ? left.slice(0, Math.max(0, inner - 3)) : left;
+    const fill = Math.max(0, inner - 1 - shownLeft.length - shownRight.length - (shownRight ? 1 : 0));
+    const background = backgroundColor ? { backgroundColor } : {};
+    return (_jsxs(Text, { wrap: "truncate", ...background, children: [_jsx(Text, { color: color, children: `╭─` }), shownLeft ? (_jsx(Text, { color: focused ? palette.accent : palette.text, bold: true, children: shownLeft })) : null, _jsx(Text, { color: color, children: '─'.repeat(fill) }), shownRight ? (_jsxs(_Fragment, { children: [_jsx(Text, { color: palette.muted, children: shownRight }), _jsx(Text, { color: color, children: "\u2500" })] })) : null, _jsx(Text, { color: color, children: "\u256E" })] }));
+}

package/dist/ui/kit/ScrollBar.js

@@ -0,0 +1,14 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Box, Text } from 'ink';
+import { palette } from '../theme/theme.js';
+/** A one-column scroll indicator: where the visible rows are within the whole list. Nothing when it all fits. */
+export function ScrollBar({ total, visible, offset, height }) {
+    if (total <= visible || height <= 0)
+        return null;
+    const thumb = Math.max(1, Math.round((visible / total) * height));
+    const start = Math.min(height - thumb, Math.round((offset / Math.max(1, total - visible)) * (height - thumb)));
+    return (_jsx(Box, { flexDirection: "column", width: 1, flexShrink: 0, children: Array.from({ length: height }, (_, row) => {
+            const inThumb = row >= start && row < start + thumb;
+            return (_jsx(Text, { color: inThumb ? palette.muted : palette.border, children: inThumb ? '┃' : '│' }, row));
+        }) }));
+}

package/dist/ui/kit/Spinner.js

@@ -0,0 +1,9 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Text, useAnimation } from 'ink';
+import { palette } from '../theme/theme.js';
+const FRAMES = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+/** Work in progress (syncing, talking to Git or GitHub). */
+export function Spinner({ label, color = palette.accent }) {
+    const { frame } = useAnimation({ interval: 80 });
+    return (_jsxs(Text, { children: [_jsx(Text, { color: color, children: FRAMES[frame % FRAMES.length] }), label ? _jsx(Text, { color: palette.muted, children: ` ${label}` }) : null] }));
+}

package/dist/ui/kit/Tabs.js

@@ -0,0 +1,12 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Box, Text } from 'ink';
+import { palette } from '../theme/theme.js';
+import { Clickable } from './Clickable.js';
+/** Filled pill for the active tab, muted text for the rest; each one clickable. */
+export function Tabs({ items, value, onChange, active = true, compact = false, }) {
+    return (_jsx(Box, { gap: compact ? 0 : 1, flexWrap: "nowrap", children: items.map((item) => {
+            const selected = item.value === value;
+            const text = `${!compact && item.shortcut ? `${item.shortcut} ` : ''}${item.label}${item.count !== undefined ? ` ${item.count}` : ''}`;
+            return (_jsx(Clickable, { onClick: () => onChange(item.value), active: active, children: _jsx(Text, { ...(selected ? { backgroundColor: palette.accent, color: palette.onAccent, bold: true } : { color: palette.muted }), children: ` ${text} ` }) }, item.value));
+        }) }));
+}

package/dist/ui/mascot/AgentScene.js

@@ -0,0 +1,30 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { memo, useEffect, useMemo, useState } from 'react';
+import { Box, Text } from 'ink';
+import { Canvas } from './engine.js';
+import { SCENES } from './scenes/index.js';
+import { defaultPalette } from './palette.js';
+/**
+ * Escena ASCII animada de mini agentes para Ink.
+ *
+ * <AgentScene scene="working" />
+ */
+export const AgentScene = memo(function AgentScene({ scene, fps = 10, paused = false, showStatus = true, statusText, palette, seed, }) {
+    const def = SCENES[scene];
+    const runtime = useMemo(() => def.create(seed), [def, seed]);
+    const colors = useMemo(() => ({ ...defaultPalette, ...palette }), [palette]);
+    const [, setFrame] = useState(0);
+    useEffect(() => {
+        if (paused)
+            return;
+        const id = setInterval(() => {
+            runtime.step();
+            setFrame((f) => f + 1);
+        }, Math.max(16, Math.round(1000 / fps)));
+        return () => clearInterval(id);
+    }, [runtime, fps, paused]);
+    const canvas = new Canvas(def.width, def.height);
+    runtime.draw(canvas);
+    const rows = canvas.rows();
+    return (_jsxs(Box, { flexDirection: "column", width: def.width, children: [rows.map((row, y) => (_jsx(Text, { wrap: "truncate", children: row.map((seg, i) => seg.tone ? (_jsx(Text, { color: colors[seg.tone], children: seg.text }, i)) : (seg.text)) }, y))), showStatus && (_jsx(Text, { dimColor: true, wrap: "truncate", children: statusText ?? runtime.status() }))] }));
+});

package/dist/ui/mascot/Mascot.js

@@ -0,0 +1,26 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useMemo } from 'react';
+import { AgentScene } from './index.js';
+import { palette } from '../theme/theme.js';
+/** The bundled scenes, recolored with SOJA's active light or dark palette. */
+export function Mascot({ scene, paused = false }) {
+    const colors = useMemo(() => ({
+        agent: palette.accent,
+        rock: palette.muted,
+        soil: palette.faint,
+        dirt: palette.warning,
+        spark: palette.warning,
+        fire: palette.danger,
+        flame: palette.warning,
+        water: palette.info,
+        good: palette.success,
+        bad: palette.danger,
+        accent: palette.accent,
+        cloud: palette.muted,
+        wood: palette.warning,
+        paper: palette.text,
+        leaf: palette.success,
+        text: palette.text,
+    }), []);
+    return _jsx(AgentScene, { scene: scene, palette: colors, fps: 4, paused: paused, showStatus: false });
+}

package/dist/ui/mascot/ansi.js

@@ -0,0 +1,25 @@
+/* eslint-disable @typescript-eslint/no-non-null-assertion -- ANSI frame encoding indexes rows created from canvas dimensions. */
+import { Canvas } from './engine.js';
+import { defaultPalette } from './palette.js';
+function hexToAnsi(hex) {
+    const m = /^#?([0-9a-f]{6})$/i.exec(hex);
+    if (!m)
+        return '';
+    const n = parseInt(m[1], 16);
+    return `\x1b[38;2;${(n >> 16) & 255};${(n >> 8) & 255};${n & 255}m`;
+}
+/** Renderiza un fotograma como texto ANSI (útil fuera de Ink: logs, CLI simple, tests). */
+export function frameToAnsi(def, runtime, palette = defaultPalette) {
+    const c = new Canvas(def.width, def.height);
+    runtime.draw(c);
+    return c
+        .rows()
+        .map((row) => row.map((s) => (s.tone ? hexToAnsi(palette[s.tone]) + s.text + '\x1b[0m' : s.text)).join(''))
+        .join('\n');
+}
+/** Renderiza un fotograma como texto plano. */
+export function frameToText(def, runtime) {
+    const c = new Canvas(def.width, def.height);
+    runtime.draw(c);
+    return c.toString();
+}