@scira/cli 0.1.0

package/dist/tools/search-web.js

@@ -0,0 +1,153 @@
+import process from "node:process";
+import { Exa } from "exa-js";
+import Parallel from "parallel-web";
+import { Firecrawl } from "@mendable/firecrawl-js";
+import { hasEnv, requireSearchProvider } from "../providers/llm/readiness.js";
+// ── lazy singleton clients ──
+let _exa;
+let _parallel;
+let _firecrawl;
+function getExa() {
+    requireSearchProvider("exa");
+    if (!_exa)
+        _exa = new Exa(process.env.EXA_API_KEY);
+    return _exa;
+}
+function getParallel() {
+    requireSearchProvider("parallel");
+    if (!_parallel)
+        _parallel = new Parallel({ apiKey: process.env.PARALLEL_API_KEY });
+    return _parallel;
+}
+function getFirecrawl() {
+    requireSearchProvider("firecrawl");
+    if (!_firecrawl)
+        _firecrawl = new Firecrawl({ apiKey: process.env.FIRECRAWL_API_KEY });
+    return _firecrawl;
+}
+// ── helpers (mirrored from scira) ──
+function extractDomain(url) {
+    if (!url || typeof url !== "string")
+        return "";
+    const match = url.match(/^https?:\/\/([^/?#]+)(?:[/?#]|$)/iu);
+    return match?.[1] || url;
+}
+function cleanTitle(title) {
+    return title
+        .replace(/\[.*?\]/gu, "")
+        .replace(/\(.*?\)/gu, "")
+        .replace(/\s+/gu, " ")
+        .trim();
+}
+function deduplicateByDomainAndUrl(items) {
+    const seenDomains = new Set();
+    const seenUrls = new Set();
+    return items.filter((item) => {
+        const domain = extractDomain(item.url);
+        if (!seenUrls.has(item.url) && !seenDomains.has(domain)) {
+            seenUrls.add(item.url);
+            seenDomains.add(domain);
+            return true;
+        }
+        return false;
+    });
+}
+// ── provider strategies ──
+async function parallelSearch(query, config, opts = {}) {
+    const parallel = getParallel();
+    const maxResults = opts.maxResults ?? config.search.maxResults;
+    const startDate = opts.startDate ?? config.search.afterDate;
+    const response = await parallel.search({
+        objective: query,
+        search_queries: [query],
+        mode: opts.quality === "best" ? "advanced" : "basic",
+        max_chars_total: config.search.maxCharsTotal ?? 5000,
+        advanced_settings: {
+            max_results: Math.max(maxResults, 10),
+            fetch_policy: { max_age_seconds: config.search.maxAgeSeconds ?? 3600, timeout_seconds: 120 },
+            ...(startDate ? { source_policy: { after_date: startDate } } : {})
+        }
+    });
+    const results = (response.results ?? []).map((r) => ({
+        url: r.url,
+        title: cleanTitle(r.title ?? ""),
+        snippet: (r.excerpts ?? []).join(" ").slice(0, 1000),
+        publishedDate: r.publish_date ?? undefined
+    }));
+    return deduplicateByDomainAndUrl(results);
+}
+async function exaSearch(query, config, opts = {}) {
+    const exa = getExa();
+    const maxResults = opts.maxResults ?? config.search.maxResults;
+    const startDate = opts.startDate ?? config.search.afterDate;
+    const startPublishedDate = startDate ? new Date(startDate).toISOString() : undefined;
+    const response = await exa.search(query, {
+        type: opts.quality === "best" ? "deep" : "auto",
+        numResults: Math.max(maxResults, 15),
+        ...(startPublishedDate ? { startPublishedDate, endPublishedDate: new Date().toISOString() } : {}),
+        contents: { highlights: true }
+    });
+    const results = (response.results ?? []).map((r) => {
+        const highlights = r.highlights ?? [];
+        return {
+            url: r.url,
+            title: cleanTitle(r.title ?? ""),
+            snippet: highlights.join(" ").slice(0, 1000),
+            publishedDate: r.publishedDate ?? undefined
+        };
+    });
+    return deduplicateByDomainAndUrl(results);
+}
+async function firecrawlSearch(query, config, opts = {}) {
+    const firecrawl = getFirecrawl();
+    const maxResults = opts.maxResults ?? config.search.maxResults;
+    const startDate = opts.startDate ?? config.search.afterDate;
+    const topic = opts.topic ?? "general";
+    const formatTbs = (d) => {
+        const dt = new Date(d);
+        const end = new Date();
+        return `cdr:1,cd_min:${dt.getMonth() + 1}/${dt.getDate()}/${dt.getFullYear()},cd_max:${end.getMonth() + 1}/${end.getDate()}/${end.getFullYear()}`;
+    };
+    const sources = topic === "news" ? ["news", "web"] : ["web"];
+    const data = await firecrawl.search(query, {
+        sources,
+        limit: maxResults,
+        ...(startDate ? { tbs: formatTbs(startDate) } : {}),
+        ...(config.search.includeDomains.length ? { includeDomains: config.search.includeDomains } : {}),
+        ...(config.search.excludeDomains.length ? { excludeDomains: config.search.excludeDomains } : {})
+    });
+    const web = (data.web ?? []).filter((item) => typeof item.url === "string");
+    const news = topic === "news"
+        ? (data.news ?? []).filter((item) => typeof item.url === "string")
+        : [];
+    const results = [
+        ...news.map((r) => ({ url: r.url, title: cleanTitle(r.title ?? ""), snippet: (r.snippet ?? "").slice(0, 1000), publishedDate: r.date })),
+        ...web.map((r) => ({ url: r.url, title: cleanTitle(r.title ?? ""), snippet: (r.description ?? "").slice(0, 1000) }))
+    ];
+    return deduplicateByDomainAndUrl(results);
+}
+const STRATEGIES = {
+    parallel: parallelSearch,
+    exa: exaSearch,
+    firecrawl: firecrawlSearch
+};
+export async function multiSearchWeb(queries, perQuery, config) {
+    const provider = config.search.provider;
+    const strategy = STRATEGIES[provider];
+    const settled = await Promise.allSettled(queries.map((q, i) => strategy(q, config, perQuery[i] ?? {})));
+    const searches = await Promise.all(settled.map(async (res, i) => {
+        if (res.status === "fulfilled" && res.value.length > 0) {
+            return { query: queries[i], results: res.value };
+        }
+        // per-query fallback to Firecrawl
+        if (provider !== "firecrawl" && hasEnv("FIRECRAWL_API_KEY")) {
+            try {
+                const fallback = await firecrawlSearch(queries[i], config, perQuery[i] ?? {});
+                return { query: queries[i], results: fallback };
+            }
+            catch { /* ignore */ }
+        }
+        return { query: queries[i], results: [] };
+    }));
+    return searches;
+}

package/dist/types/index.js

@@ -0,0 +1,91 @@
+import { z } from "zod";
+export const ApprovalModeSchema = z.enum(["manual", "suggest", "auto"]);
+export const SciraConfigSchema = z.object({
+    llmProvider: z.enum(["gateway", "xai", "workers-ai", "huggingface"]).default("gateway"),
+    model: z.string().default("deepseek/deepseek-v4-flash"),
+    // last selected model per LLM provider, restored when switching back
+    lastModels: z.record(z.string(), z.string()).default({}),
+    approvalMode: ApprovalModeSchema.default("suggest"),
+    runDirectory: z.string().default(".scira/runs"),
+    maxSources: z.number().int().min(1).max(100).default(20),
+    citationPolicy: z.enum(["strict", "balanced"]).default("strict"),
+    search: z.object({
+        provider: z.enum(["parallel", "exa", "firecrawl"]).default("exa"),
+        maxResults: z.number().int().min(1).max(20).default(8),
+        includeDomains: z.array(z.string()).default([]),
+        excludeDomains: z.array(z.string()).default([]),
+        afterDate: z.string().optional(),
+        maxAgeSeconds: z.number().int().positive().optional(),
+        maxCharsTotal: z.number().int().positive().optional()
+    }).default({
+        provider: "exa",
+        maxResults: 20,
+        includeDomains: [],
+        excludeDomains: []
+    }),
+    files: z.object({
+        dir: z.string().describe("Absolute or relative path to the local files directory.")
+    }).optional(),
+    mcp: z.object({
+        chromeDevtools: z.object({
+            enabled: z.boolean().default(false),
+            command: z.string().default("npx"),
+            args: z.array(z.string()).default(["-y", "chrome-devtools-mcp@latest"]),
+            toolPrefix: z.string().default("devtools_")
+        }).default({
+            enabled: false,
+            command: "npx",
+            args: ["-y", "chrome-devtools-mcp@latest"],
+            toolPrefix: "devtools_"
+        }),
+        servers: z.array(z.object({
+            name: z.string(),
+            transport: z.enum(["stdio", "sse", "http"]).default("stdio"),
+            command: z.string().optional(),
+            args: z.array(z.string()).default([]),
+            url: z.string().optional(),
+            toolPrefix: z.string().default(""),
+            env: z.record(z.string(), z.string()).default({}),
+            enabled: z.boolean().default(true),
+            authType: z.enum(["none", "bearer", "header", "oauth"]).default("none"),
+            bearerToken: z.string().optional(),
+            headerName: z.string().optional(),
+            headerValue: z.string().optional(),
+            oauthClientId: z.string().optional(),
+            oauthClientSecret: z.string().optional(),
+            oauthIssuerUrl: z.string().optional(),
+            oauthAuthorizationUrl: z.string().optional(),
+            oauthTokenUrl: z.string().optional(),
+            oauthScopes: z.string().optional(),
+            oauthAccessToken: z.string().optional(),
+            oauthRefreshToken: z.string().optional(),
+            oauthTokenExpiresAt: z.number().optional()
+        })).default([])
+    }).default({
+        chromeDevtools: {
+            enabled: false,
+            command: "npx",
+            args: ["-y", "chrome-devtools-mcp@latest"],
+            toolPrefix: "devtools_"
+        },
+        servers: []
+    })
+});
+export const SourceSchema = z.object({
+    id: z.string(),
+    title: z.string(),
+    url: z.string(),
+    kind: z.enum(["primary", "secondary", "vendor", "weak", "unknown"]).default("unknown"),
+    summary: z.string().default(""),
+    snapshotPath: z.string().optional(),
+    createdAt: z.string()
+});
+export const ClaimSchema = z.object({
+    id: z.string(),
+    text: z.string(),
+    confidence: z.enum(["low", "medium", "high"]).default("medium"),
+    status: z.enum(["draft", "verified", "weak", "contradicted", "needs_review"]).default("draft"),
+    sourceIds: z.array(z.string()).default([]),
+    reason: z.string().default(""),
+    createdAt: z.string()
+});

package/dist/types/schema.test.js

@@ -0,0 +1,60 @@
+import { describe, it, expect } from "vitest";
+import { ClaimSchema, SourceSchema, SciraConfigSchema } from "./index.js";
+describe("ClaimSchema", () => {
+    it("parses a valid claim with defaults", () => {
+        const result = ClaimSchema.parse({
+            id: "c1",
+            text: "The sky is blue.",
+            createdAt: new Date().toISOString(),
+        });
+        expect(result.confidence).toBe("medium");
+        expect(result.status).toBe("draft");
+        expect(result.sourceIds).toEqual([]);
+        expect(result.reason).toBe("");
+    });
+    it("rejects an invalid confidence value", () => {
+        expect(() => ClaimSchema.parse({ id: "c1", text: "x", confidence: "very_high", createdAt: "" })).toThrow();
+    });
+    it("rejects an invalid status value", () => {
+        expect(() => ClaimSchema.parse({ id: "c1", text: "x", status: "maybe", createdAt: "" })).toThrow();
+    });
+    it("preserves all fields when fully specified", () => {
+        const input = {
+            id: "c2",
+            text: "Claim text.",
+            confidence: "high",
+            status: "verified",
+            sourceIds: ["s1", "s2"],
+            reason: "Verified by primary source.",
+            createdAt: "2026-01-01T00:00:00.000Z",
+        };
+        expect(ClaimSchema.parse(input)).toEqual(input);
+    });
+});
+describe("SourceSchema", () => {
+    it("parses a valid source with defaults", () => {
+        const result = SourceSchema.parse({
+            id: "s1",
+            title: "Example",
+            url: "https://example.com",
+            createdAt: new Date().toISOString(),
+        });
+        expect(result.kind).toBe("unknown");
+        expect(result.summary).toBe("");
+    });
+    it("rejects an invalid kind value", () => {
+        expect(() => SourceSchema.parse({ id: "s1", title: "t", url: "u", kind: "blog", createdAt: "" })).toThrow();
+    });
+});
+describe("SciraConfigSchema", () => {
+    it("parses an empty object using all defaults", () => {
+        const config = SciraConfigSchema.parse({});
+        expect(config.llmProvider).toBe("gateway");
+        expect(config.approvalMode).toBe("suggest");
+        expect(config.runDirectory).toBe(".scira/runs");
+        expect(config.maxSources).toBe(20);
+    });
+    it("rejects an invalid approvalMode", () => {
+        expect(() => SciraConfigSchema.parse({ approvalMode: "yolo" })).toThrow();
+    });
+});

package/dist/ui/ink/SciraApp.js

@@ -0,0 +1,274 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import React, { useCallback, useMemo, useRef, useState } from "react";
+import { Box, useApp, useStdout, useStdin } from "ink";
+import { CHAT_COMMANDS, MENU_VISIBLE } from "./constants.js";
+import { CWD_DISPLAY, wrapText, wrapInputWithCursor, loadInputHistory, saveInputHistory } from "./lib/utils.js";
+import { deleteRun } from "../../storage/run-store.js";
+import { useMountEffect, TipCycler, AnimationTick, MouseTracker } from "./components/effects.js";
+import { useFeedLines, computeGroups } from "./hooks/use-feed-lines.js";
+import { useAgentTurn } from "./hooks/use-agent-turn.js";
+import { TopBar, InputBar, HintLine, CommandMenuBox, HelpBox, ApprovalBox, MenuDialog, McpDialog } from "./components/overlays.js";
+import { useKeyboard } from "./hooks/use-keyboard.js";
+import { HomeScreen } from "./components/home-screen.js";
+import { useFeed } from "./hooks/use-feed.js";
+import { useSettings } from "./hooks/use-settings.js";
+import { useSuggestions } from "./hooks/use-suggestions.js";
+import { useSubmit } from "./hooks/use-submit.js";
+import { useSession } from "./hooks/use-session.js";
+import { useMouse } from "./hooks/use-mouse.js";
+export function SciraApp({ runPath: initialRunPath, config: initialConfig }) {
+    const { exit } = useApp();
+    const { stdout } = useStdout();
+    const { stdin } = useStdin();
+    const [size, setSize] = useState({ cols: stdout?.columns ?? 120, rows: stdout?.rows ?? 30 });
+    const cols = size.cols;
+    const rows = size.rows;
+    useMountEffect(() => {
+        if (!stdout)
+            return;
+        const onResize = () => setSize({ cols: stdout.columns, rows: stdout.rows });
+        stdout.on("resize", onResize);
+        return () => { stdout.off("resize", onResize); };
+    });
+    const [screen, setScreen] = useState(initialRunPath ? "chat" : "home");
+    const [currentRunPath, setCurrentRunPath] = useState(initialRunPath);
+    const [config, setConfig] = useState(initialConfig);
+    const [notice, setNotice] = useState("");
+    const [pendingRerun, setPendingRerun] = useState(false);
+    const [mcpOpen, setMcpOpen] = useState(false);
+    const [sessions, setSessions] = useState([]);
+    const [selectedIdx, setSelectedIdx] = useState(0);
+    const [sessionsModalOpen, setSessionsModalOpen] = useState(false);
+    const [sessionsModalIdx, setSessionsModalIdx] = useState(0);
+    const [runState, setRunState] = useState(null);
+    const { feed, setFeed, feedRef, pushFeed, appendText, appendReasoning, finishReasoning, markToolDone } = useFeed();
+    const conversationRef = useRef([]);
+    const queuedPromptRef = useRef(null);
+    const startedRef = useRef(undefined);
+    const fullModeRef = useRef(false);
+    const [fullMode, setFullModeState] = useState(false);
+    const setMode = useCallback((full) => { fullModeRef.current = full; setFullModeState(full); }, []);
+    const [usage, setUsage] = useState({});
+    const turnsRef = useRef([]);
+    const recordUsage = useCallback((model, u) => {
+        const input = u.inputTokens ?? 0;
+        const output = u.outputTokens ?? 0;
+        const total = u.totalTokens ?? input + output;
+        if (input + output + total === 0)
+            return;
+        setUsage((prev) => {
+            const cur = prev[model] ?? { input: 0, output: 0, total: 0, turns: 0 };
+            return { ...prev, [model]: { input: cur.input + input, output: cur.output + output, total: cur.total + total, turns: cur.turns + 1 } };
+        });
+    }, []);
+    const [approvalPending, setApprovalPending] = useState(null);
+    const [inputText, setInputText] = useState("");
+    const [cursorPos, setCursorPos] = useState(0);
+    const [inputHistory, setInputHistory] = useState([]);
+    const [historyIndex, setHistoryIndex] = useState(-1);
+    const [heroHidden, setHeroHidden] = useState(false);
+    const [busy, setBusy] = useState(false);
+    const [blink, setBlink] = useState(true);
+    const [frame, setFrame] = useState(0);
+    const [reasoningTick, setReasoningTick] = useState(0);
+    const [commandMenuIndex, setCommandMenuIndex] = useState(0);
+    const [helpOpen, setHelpOpen] = useState(false);
+    const [scrollOffset, setScrollOffset] = useState(0);
+    const [collapsedGroups, setCollapsedGroups] = useState(new Set());
+    const [focusedGroupKey, setFocusedGroupKey] = useState(null);
+    const [pendingCollapse, setPendingCollapse] = useState(new Set());
+    const doneGroupKeys = useMemo(() => {
+        const { groups } = computeGroups(feed);
+        return [...groups.entries()].filter(([, g]) => !g.active).map(([k]) => k).sort((a, b) => a - b);
+    }, [feed]);
+    const toggleAllGroups = useCallback(() => {
+        setCollapsedGroups((prev) => {
+            const allCollapsed = doneGroupKeys.length > 0 && doneGroupKeys.every((k) => prev.has(k));
+            if (allCollapsed) {
+                setPendingCollapse(new Set());
+                return new Set();
+            }
+            // Mark done groups for pending collapse, but don't collapse active ones
+            setPendingCollapse(new Set(doneGroupKeys));
+            return new Set(doneGroupKeys.filter((k) => {
+                const group = computeGroups(feed).groups.get(k);
+                return group && !group.active;
+            }));
+        });
+    }, [doneGroupKeys, feed]);
+    const toggleFocusedGroup = useCallback(() => {
+        if (focusedGroupKey === null)
+            return;
+        setCollapsedGroups((prev) => {
+            const next = new Set(prev);
+            if (next.has(focusedGroupKey))
+                next.delete(focusedGroupKey);
+            else
+                next.add(focusedGroupKey);
+            return next;
+        });
+    }, [focusedGroupKey]);
+    // Auto-collapse groups when they become inactive if they're in pendingCollapse
+    React.useEffect(() => {
+        if (pendingCollapse.size === 0)
+            return;
+        const { groups } = computeGroups(feed);
+        const nowInactive = [...pendingCollapse].filter((k) => {
+            const group = groups.get(k);
+            return group && !group.active;
+        });
+        if (nowInactive.length > 0) {
+            setCollapsedGroups((prev) => {
+                const next = new Set(prev);
+                nowInactive.forEach((k) => next.add(k));
+                return next;
+            });
+            setPendingCollapse((prev) => {
+                const next = new Set(prev);
+                nowInactive.forEach((k) => next.delete(k));
+                return next;
+            });
+        }
+    }, [feed, pendingCollapse]);
+    const focusPrevGroup = useCallback(() => {
+        setFocusedGroupKey((prev) => {
+            if (doneGroupKeys.length === 0)
+                return null;
+            if (prev === null)
+                return doneGroupKeys[doneGroupKeys.length - 1] ?? null;
+            const idx = doneGroupKeys.indexOf(prev);
+            return idx <= 0 ? prev : (doneGroupKeys[idx - 1] ?? prev);
+        });
+    }, [doneGroupKeys]);
+    const focusNextGroup = useCallback(() => {
+        setFocusedGroupKey((prev) => {
+            if (doneGroupKeys.length === 0)
+                return null;
+            if (prev === null)
+                return doneGroupKeys[0] ?? null;
+            const idx = doneGroupKeys.indexOf(prev);
+            return idx < 0 || idx >= doneGroupKeys.length - 1 ? prev : (doneGroupKeys[idx + 1] ?? prev);
+        });
+    }, [doneGroupKeys]);
+    const unfocusGroup = useCallback(() => setFocusedGroupKey(null), []);
+    const [tipIndex, setTipIndex] = useState(0);
+    React.useEffect(() => {
+        if (!notice)
+            return;
+        const id = setTimeout(() => setNotice(""), 4000);
+        return () => clearTimeout(id);
+    }, [notice]);
+    const wheelStateRef = useRef({ screen, maxScrollOffset: 0 });
+    const handleWheel = useCallback((dir) => {
+        if (wheelStateRef.current.screen !== "chat")
+            return;
+        setScrollOffset((off) => Math.max(0, Math.min(off + dir * 3, wheelStateRef.current.maxScrollOffset)));
+    }, []);
+    const { clickMapRef, hoverMapRef, hoveredIdx, setHoveredIdx, handleMouseData } = useMouse(handleWheel);
+    const getSubscriber = useCallback(() => ({
+        pushFeed,
+        appendText,
+        appendReasoning,
+        finishReasoning,
+        markToolDone,
+        onBusyChange: setBusy,
+        onApprovalRequired: (p) => setApprovalPending(p),
+        onApprovalCleared: () => setApprovalPending(null),
+        onEscalate: () => setMode(true),
+        onModeChange: setMode,
+    }), [pushFeed, appendText, appendReasoning, finishReasoning, markToolDone, setBusy, setApprovalPending, setMode]);
+    const runTurnRef = useRef(async () => { });
+    const { refreshSessions, refreshRun, openRun: openRunBase } = useSession({
+        config, currentRunPath, conversationRef, feedRef, turnsRef, startedRef, runTurnRef,
+        setSessions, setRunState, setCurrentRunPath, setInputText, setCursorPos,
+        setFeed, setUsage, setScrollOffset, setScreen, setMode,
+        setBusy, setApprovalPending, getSubscriber,
+    });
+    const openRun = useCallback(async (runPath, initialQuestion) => {
+        setPendingRerun(false);
+        await openRunBase(runPath, initialQuestion);
+    }, [openRunBase, setPendingRerun]);
+    useMountEffect(() => {
+        if (!initialRunPath)
+            void refreshSessions();
+        void loadInputHistory(config.runDirectory).then((h) => { if (h.length > 0)
+            setInputHistory(h); });
+    });
+    React.useEffect(() => {
+        if (inputHistory.length > 0)
+            void saveInputHistory(config.runDirectory, inputHistory);
+    }, [inputHistory, config.runDirectory]);
+    const deleteSession = useCallback((idx) => {
+        const s = sessions[idx];
+        if (!s)
+            return;
+        void (async () => {
+            await deleteRun(s.path).catch(() => { });
+            await refreshSessions();
+            setSessionsModalIdx((i) => Math.max(0, Math.min(i, sessions.length - 2)));
+            setNotice("Session deleted.");
+        })();
+    }, [sessions, refreshSessions]);
+    const { menu, setMenu, modelName, openMenu, applyMenuSelection, handleSettings } = useSettings({
+        config, setConfig, screen, pushFeed, setNotice,
+    });
+    const { runTurn } = useAgentTurn({
+        config, currentRunPath, queuedPromptRef, fullModeRef, conversationRef, turnsRef, feedRef,
+        setBusy, setScrollOffset, refreshRun, recordUsage, setMode, getSubscriber,
+    });
+    runTurnRef.current = runTurn;
+    const { submitHome, submitChat, stopTurn } = useSubmit({
+        state: { config, currentRunPath, sessions, selectedIdx, busy, usage, pendingRerun },
+        refs: { queuedPromptRef, conversationRef, feedRef },
+        setters: {
+            setApprovalPending, setInputText, setCursorPos, setInputHistory, setHistoryIndex, setHelpOpen,
+            setNotice, setBusy, setScreen, setFeed, setRunState, setPendingRerun, setMode, setConfig, setMcpOpen,
+            setHeroHidden,
+        },
+        actions: { pushFeed, refreshSessions, openRun, openMenu, handleSettings, runTurn, exit },
+    });
+    const { activeSuggestions, activeSuggestionKind, acceptActiveSuggestion } = useSuggestions({
+        inputText, setInputText, setCursorPos, sessions, openRun, refreshSessions,
+    });
+    const innerWidth = Math.max(20, cols - 4);
+    const boxWidth = Math.max(20, cols - 4);
+    const textWidth = Math.max(1, boxWidth - 6);
+    const rawInputText = approvalPending ? "waiting for approval\u2026" : inputText;
+    const showCursor = !busy && !approvalPending;
+    const caret = Math.max(0, Math.min(cursorPos, inputText.length));
+    const { lines: inputLines, cursorLine, cursorCol } = wrapInputWithCursor(rawInputText, textWidth, showCursor ? caret : -1);
+    const commandMenuHeight = activeSuggestions.length > 0 ? Math.min(MENU_VISIBLE, activeSuggestions.length) + 3 : 0;
+    const helpHeight = helpOpen ? Math.min(14, CHAT_COMMANDS.length + 4) : 0;
+    const approvalPreviewLines = approvalPending
+        ? Math.min(5, wrapText(approvalPending.description, Math.max(10, innerWidth - 4)).length)
+        : 0;
+    const approvalHeight = approvalPending ? approvalPreviewLines + 5 : 0;
+    const menuHeight = commandMenuHeight + helpHeight + approvalHeight;
+    const feedRows = Math.max(3, rows - 6 - inputLines.length - menuHeight);
+    const hasRunningTool = feed.some((it) => it.kind === "tool" && it.status === "running");
+    const feedLines = useFeedLines(feed, innerWidth, reasoningTick, hasRunningTool ? frame : 0, collapsedGroups, focusedGroupKey);
+    const contentRows = Math.max(1, feedRows);
+    const maxScrollOffset = Math.max(0, feedLines.length - contentRows);
+    wheelStateRef.current = { screen, maxScrollOffset };
+    const clampedOffset = Math.min(scrollOffset, maxScrollOffset);
+    const startIdx = Math.max(0, feedLines.length - contentRows - clampedOffset);
+    const visibleLines = feedLines.slice(startIdx, startIdx + contentRows);
+    const scrollLabel = clampedOffset > 0
+        ? (startIdx > 0 ? `↑ ${startIdx} · ↓ ${clampedOffset} · wheel/⇞⇟` : `top · ↓ ${clampedOffset} · wheel/⇞⇟`)
+        : "";
+    useKeyboard({
+        screen,
+        setNotice,
+        exit,
+        input: { text: inputText, setText: setInputText, cursorPos, setCursorPos, history: inputHistory, historyIndex, setHistoryIndex },
+        dialogs: { approvalPending, setApprovalPending, menu, setMenu, applyMenuSelection, helpOpen, setHelpOpen, mcpOpen, setMcpOpen },
+        suggestions: { activeSuggestions, activeSuggestionKind, commandMenuIndex, setCommandMenuIndex, acceptActiveSuggestion },
+        chat: { setScrollOffset, contentRows, maxScrollOffset, pendingRerun, setPendingRerun, busy, stopTurn, submitChat, toggleAllGroups, toggleFocusedGroup, focusPrevGroup, focusNextGroup, unfocusGroup, hasFocusedGroup: focusedGroupKey !== null },
+        home: { sessionsModalOpen, setSessionsModalOpen, sessionsModalIdx, setSessionsModalIdx, sessions, deleteSession, selectedIdx, setSelectedIdx, setHeroHidden, openRun, submitHome },
+    });
+    const activeUsage = usage[config.model];
+    if (screen === "home") {
+        return (_jsxs(Box, { flexDirection: "column", width: cols, height: rows, paddingX: 2, children: [_jsx(TipCycler, { setTipIndex: setTipIndex }), !sessionsModalOpen && stdout !== undefined && stdin !== undefined && (_jsx(MouseTracker, { stdout: stdout, stdin: stdin, onData: handleMouseData, onUnmount: () => setHoveredIdx(null) })), busy && _jsx(AnimationTick, { setBlink: setBlink, setFrame: setFrame, setReasoningTick: setReasoningTick }), _jsx(TopBar, { screen: screen, runState: runState, fullMode: fullMode, activeUsage: activeUsage, busy: busy, frame: frame, cwdDisplay: CWD_DISPLAY }), _jsx(HomeScreen, { cols: cols, rows: rows, sessions: sessions, selectedIdx: selectedIdx, hoveredIdx: hoveredIdx, heroHidden: heroHidden, notice: notice, tipIndex: tipIndex, commandMenuHeight: commandMenuHeight, sessionsModalOpen: sessionsModalOpen, sessionsModalIdx: sessionsModalIdx, inputText: inputText, clickMapRef: clickMapRef, hoverMapRef: hoverMapRef, setSelectedIdx: setSelectedIdx, setSessionsModalOpen: setSessionsModalOpen, setSessionsModalIdx: setSessionsModalIdx, setNotice: setNotice, openRun: openRun, submitHome: submitHome, exit: exit }), _jsxs(Box, { flexDirection: "column", backgroundColor: "#141414", paddingBottom: 1, children: [_jsx(CommandMenuBox, { activeSuggestions: activeSuggestions, activeSuggestionKind: activeSuggestionKind, commandMenuIndex: commandMenuIndex, innerWidth: innerWidth, sessions: sessions }), _jsx(InputBar, { inputLines: inputLines, cursorLine: cursorLine, cursorCol: cursorCol, showCursor: showCursor, approvalPending: !!approvalPending, busy: busy, frame: frame, boxWidth: boxWidth, modelName: modelName }), _jsx(HintLine, { screen: screen, busy: busy })] }), _jsx(MenuDialog, { menu: menu, cols: cols, rows: rows }), _jsx(McpDialog, { open: mcpOpen, config: config, cols: cols, rows: rows })] }));
+    }
+    return (_jsxs(Box, { flexDirection: "column", width: cols, height: rows, paddingX: 2, children: [stdout !== undefined && stdin !== undefined && (_jsx(MouseTracker, { stdout: stdout, stdin: stdin, onData: handleMouseData, onUnmount: () => setHoveredIdx(null) })), busy && _jsx(AnimationTick, { setBlink: setBlink, setFrame: setFrame, setReasoningTick: setReasoningTick }), _jsx(TopBar, { screen: screen, runState: runState, fullMode: fullMode, activeUsage: activeUsage, busy: busy, frame: frame, cwdDisplay: CWD_DISPLAY }), _jsx(Box, { flexDirection: "column", flexGrow: 1, paddingTop: 1, overflow: "hidden", children: visibleLines }), _jsxs(Box, { flexDirection: "column", backgroundColor: "#141414", paddingBottom: 1, children: [_jsx(CommandMenuBox, { activeSuggestions: activeSuggestions, activeSuggestionKind: activeSuggestionKind, commandMenuIndex: commandMenuIndex, innerWidth: innerWidth, sessions: sessions }), _jsx(HelpBox, { open: helpOpen, innerWidth: innerWidth }), approvalPending && _jsx(ApprovalBox, { toolName: approvalPending.toolName, description: approvalPending.description, innerWidth: innerWidth }), _jsx(InputBar, { inputLines: inputLines, cursorLine: cursorLine, cursorCol: cursorCol, showCursor: showCursor, approvalPending: !!approvalPending, busy: busy, frame: frame, boxWidth: boxWidth, modelName: modelName }), _jsx(HintLine, { screen: screen, busy: busy, scrollLabel: scrollLabel, hasDoneGroups: doneGroupKeys.length > 0, hasFocusedGroup: focusedGroupKey !== null })] }), _jsx(MenuDialog, { menu: menu, cols: cols, rows: rows }), _jsx(McpDialog, { open: mcpOpen, config: config, cols: cols, rows: rows })] }));
+}

package/dist/ui/ink/components/effects.js

@@ -0,0 +1,44 @@
+import React from "react";
+import { HOME_TIPS, SPINNER_FRAMES } from "../constants.js";
+/** Stable mount-only effect: makes intent explicit, prevents accidental dep-driven re-runs. */
+export function useMountEffect(effect) {
+    /* eslint-disable-next-line react-hooks/exhaustive-deps */
+    React.useEffect(effect, []);
+}
+/** Cycles the tip index every 6 s while mounted (rendered only on the home screen). */
+export function TipCycler({ setTipIndex }) {
+    useMountEffect(() => {
+        const id = setInterval(() => setTipIndex((i) => (i + 1) % HOME_TIPS.length), 6000);
+        return () => clearInterval(id);
+    });
+    return null;
+}
+/** Drives the spinner, caret-blink, and reasoning-clock animations while mounted (rendered only when busy). */
+export function AnimationTick({ setBlink, setFrame, setReasoningTick, }) {
+    useMountEffect(() => {
+        const blinkId = setInterval(() => setBlink((v) => !v), 400);
+        const frameId = setInterval(() => setFrame((f) => (f + 1) % SPINNER_FRAMES.length), 80);
+        const tickId = setInterval(() => setReasoningTick((t) => t + 1), 500);
+        return () => {
+            clearInterval(blinkId);
+            clearInterval(frameId);
+            clearInterval(tickId);
+            setBlink(true);
+            setFrame(0);
+        };
+    });
+    return null;
+}
+/** Enables SGR mouse-click/hover tracking while mounted (rendered only on the home screen). */
+export function MouseTracker({ stdout, stdin, onData, onUnmount, }) {
+    useMountEffect(() => {
+        stdout.write("\x1b[?1003h\x1b[?1006h");
+        stdin.on("data", onData);
+        return () => {
+            stdin.off("data", onData);
+            onUnmount();
+            stdout.write("\x1b[?1003l\x1b[?1006l");
+        };
+    });
+    return null;
+}