castle-web-cli 0.4.0 → 0.4.2

package/dist/ide-client.js

@@ -0,0 +1,537 @@
+// Browser-side terminal for the `castle-web serve --ide` panel. Plain DOM (no
+// framework) so it can be served straight from dist with no bundler. xterm.js
+// and addon-fit are loaded as UMD <script> tags before this file, so they
+// arrive as the `Terminal` and `FitAddon` globals.
+//
+// Workarounds ported from castle-cli's `ide` branch and lemo threads' xterm:
+// backoff reconnect + wake handlers, screen replay with a multi-stage repaint
+// repair, FitAddon resize with send-dedup, wheel scroll-chain containment, and
+// the text-presentation fix for symbols browsers like to emoji-render.
+(function () {
+    const host = document.getElementById('term-host');
+    if (!host)
+        return;
+    const toggleButton = document.getElementById('term-toggle');
+    const reconnectDelaysMs = [250, 500, 1000, 2000, 4000, 8000, 12000, 15000];
+    // After a replay, xterm's grid can render at a stale size until a few
+    // repaints land; threads found this cadence reliable.
+    const replayRepairDelaysMs = [50, 160];
+    // Force text presentation for symbols browsers render as wide colour emoji;
+    // without it bullets/arrows in CLI output break the terminal grid.
+    const textPresentationPattern = /[•‣⁃∙■-◿☀-➿⬀-⯿]/g;
+    const variationSelectorText = '︎';
+    function forceTextSymbols(value) {
+        return value.replace(textPresentationPattern, (c) => `${c}${variationSelectorText}`);
+    }
+    // Terminal themes. The dark palette is Tokyo Night (from the cli `ide`
+    // branch); the choice persists in localStorage and is set from the cog.
+    const lightTheme = {
+        background: '#ffffff',
+        foreground: '#1f2328',
+        cursor: '#1f2328',
+        cursorAccent: '#ffffff',
+        selectionBackground: '#cfe0ff',
+        selectionForeground: '#1f2328',
+        black: '#24292e',
+        red: '#cf222e',
+        green: '#116329',
+        yellow: '#7d4e00',
+        blue: '#0969da',
+        magenta: '#8250df',
+        cyan: '#1b7c83',
+        white: '#6e7781',
+        brightBlack: '#57606a',
+        brightRed: '#a40e26',
+        brightGreen: '#1a7f37',
+        brightYellow: '#9a6700',
+        brightBlue: '#218bff',
+        brightMagenta: '#a475f9',
+        brightCyan: '#3192aa',
+        brightWhite: '#8c959f',
+    };
+    const darkTheme = {
+        background: '#1a1b26',
+        foreground: '#c0caf5',
+        cursor: '#c0caf5',
+        cursorAccent: '#1a1b26',
+        selectionBackground: '#283457',
+        selectionForeground: '#c0caf5',
+        black: '#15161e',
+        red: '#f7768e',
+        green: '#9ece6a',
+        yellow: '#e0af68',
+        blue: '#7aa2f7',
+        magenta: '#bb9af7',
+        cyan: '#7dcfff',
+        white: '#a9b1d6',
+        brightBlack: '#414868',
+        brightRed: '#f7768e',
+        brightGreen: '#9ece6a',
+        brightYellow: '#e0af68',
+        brightBlue: '#7aa2f7',
+        brightMagenta: '#bb9af7',
+        brightCyan: '#7dcfff',
+        brightWhite: '#c0caf5',
+    };
+    const themeStorageKey = 'castle-terminal-theme';
+    function storedThemeName() {
+        try {
+            return localStorage.getItem(themeStorageKey) === 'dark' ? 'dark' : 'light';
+        }
+        catch {
+            return 'light';
+        }
+    }
+    let themeName = storedThemeName();
+    const term = new Terminal({
+        convertEol: false,
+        cursorBlink: true,
+        macOptionIsMeta: true,
+        fontFamily: 'ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace',
+        fontSize: 12,
+        fontWeight: 400,
+        fontWeightBold: 700,
+        letterSpacing: 0,
+        lineHeight: 1.25,
+        scrollback: 4000,
+        theme: themeName === 'dark' ? darkTheme : lightTheme,
+    });
+    const fit = new FitAddon.FitAddon();
+    term.loadAddon(fit);
+    term.open(host);
+    fit.fit();
+    term.focus();
+    // The PTY is lazy: the WebSocket isn't opened (and the server doesn't spawn
+    // a shell) until the user first reveals the terminal. If they never click
+    // the toggle, no PTY ever runs.
+    let activated = false;
+    let socket = null;
+    let socketToken = 0;
+    let reconnectAttempt = 0;
+    let reconnectTimer = null;
+    let reconnectEnabled = true;
+    let needsWakeReconnect = document.visibilityState === 'hidden';
+    let lastSentCols = 0;
+    let lastSentRows = 0;
+    const intentionallyClosed = new WeakSet();
+    const replayRepairFrames = [];
+    const replayRepairTimers = [];
+    const wsProtocol = window.location.protocol === 'https:' ? 'wss:' : 'ws:';
+    const wsUrl = `${wsProtocol}//${window.location.host}/__castle/pty`;
+    //
+    // Toggle: hide the panel without unmounting / resizing xterm, so the text
+    // layout survives a hide/show cycle untouched (CSS keeps #term at 500px).
+    //
+    const openStorageKey = 'castle-terminal-open';
+    function storedOpen() {
+        try {
+            return localStorage.getItem(openStorageKey) === '1';
+        }
+        catch {
+            return false;
+        }
+    }
+    function persistOpen(open) {
+        try {
+            localStorage.setItem(openStorageKey, open ? '1' : '0');
+        }
+        catch {
+            /* storage disabled -- state just won't persist */
+        }
+    }
+    // First reveal spawns the PTY; later reveals just re-focus a live one.
+    function activateTerminal() {
+        if (activated)
+            return;
+        activated = true;
+        connect();
+    }
+    if (toggleButton) {
+        toggleButton.addEventListener('click', () => {
+            const open = document.body.classList.toggle('term-open');
+            persistOpen(open);
+            // The header strip is a flex item that appears/disappears with
+            // `term-open`, so the xterm host's leftover height changes -- re-fit so
+            // the grid matches the new content height (the ResizeObserver also
+            // catches this, but fit here makes the relayout immediate).
+            fitAndSendResize();
+            if (!open) {
+                document.body.classList.remove('term-settings-open');
+                return;
+            }
+            activateTerminal();
+            term.focus();
+        });
+    }
+    //
+    // Settings cog: a small popover with a light/dark theme switch for the
+    // terminal. The choice persists in localStorage.
+    //
+    const settingsButton = document.getElementById('term-settings');
+    const settingsPanel = document.getElementById('term-settings-panel');
+    const segButtons = Array.from(document.querySelectorAll('#term-theme-seg button'));
+    function applyTheme(name) {
+        themeName = name;
+        term.options.theme = name === 'dark' ? darkTheme : lightTheme;
+        document.body.classList.toggle('term-dark', name === 'dark');
+        for (const button of segButtons) {
+            button.classList.toggle('active', button.dataset.theme === name);
+        }
+        try {
+            localStorage.setItem(themeStorageKey, name);
+        }
+        catch {
+            /* storage disabled -- theme just won't persist */
+        }
+    }
+    applyTheme(themeName);
+    if (settingsButton) {
+        settingsButton.addEventListener('click', (event) => {
+            event.stopPropagation();
+            document.body.classList.toggle('term-settings-open');
+        });
+    }
+    for (const button of segButtons) {
+        button.addEventListener('click', () => {
+            applyTheme(button.dataset.theme === 'dark' ? 'dark' : 'light');
+        });
+    }
+    // A click anywhere outside the popover (or cog) closes it.
+    document.addEventListener('click', (event) => {
+        if (!document.body.classList.contains('term-settings-open'))
+            return;
+        const target = event.target;
+        if (settingsPanel && settingsPanel.contains(target))
+            return;
+        if (settingsButton && settingsButton.contains(target))
+            return;
+        document.body.classList.remove('term-settings-open');
+    });
+    //
+    // Ctrl+T moves keyboard focus between the terminal and the deck iframe.
+    // While the iframe holds focus the parent sees no keydowns, so the deck
+    // page forwards Ctrl+T via postMessage (see DECK_FOCUS_SCRIPT in ide.ts).
+    // The focused side persists in localStorage and is restored on load.
+    //
+    const deckFrame = document.getElementById('deck-frame');
+    const focusStorageKey = 'castle-terminal-focus';
+    function storedFocus() {
+        try {
+            return localStorage.getItem(focusStorageKey) === 'terminal' ? 'terminal' : 'deck';
+        }
+        catch {
+            return 'deck';
+        }
+    }
+    let focusTarget = storedFocus();
+    function setFocus(target) {
+        focusTarget = target;
+        try {
+            localStorage.setItem(focusStorageKey, target);
+        }
+        catch {
+            /* storage disabled -- focus side just won't persist */
+        }
+        if (target === 'terminal') {
+            // Focusing the terminal implies revealing it.
+            if (!document.body.classList.contains('term-open')) {
+                document.body.classList.add('term-open');
+                persistOpen(true);
+                activateTerminal();
+            }
+            term.focus();
+        }
+        else {
+            deckFrame?.contentWindow?.focus();
+        }
+    }
+    function toggleFocus() {
+        setFocus(focusTarget === 'terminal' ? 'deck' : 'terminal');
+    }
+    // Ctrl+T while the parent (terminal or shell chrome) holds focus. Capture
+    // phase + stopImmediatePropagation so xterm never receives the keystroke.
+    document.addEventListener('keydown', (event) => {
+        if (event.ctrlKey &&
+            !event.metaKey &&
+            !event.altKey &&
+            !event.shiftKey &&
+            (event.key === 't' || event.key === 'T')) {
+            event.preventDefault();
+            event.stopImmediatePropagation();
+            toggleFocus();
+        }
+    }, true);
+    // Ctrl+T forwarded from inside the deck iframe.
+    window.addEventListener('message', (event) => {
+        if (!event.data || event.data.type !== 'castle-ide-toggle-focus')
+            return;
+        if (deckFrame && event.source !== deckFrame.contentWindow)
+            return;
+        toggleFocus();
+    });
+    // Keep focusTarget honest when focus moves by click rather than Ctrl+T.
+    if (term.textarea) {
+        term.textarea.addEventListener('focus', () => {
+            focusTarget = 'terminal';
+        });
+    }
+    window.addEventListener('blur', () => {
+        if (deckFrame && document.activeElement === deckFrame)
+            focusTarget = 'deck';
+    });
+    function clearReconnectTimer() {
+        if (reconnectTimer === null)
+            return;
+        window.clearTimeout(reconnectTimer);
+        reconnectTimer = null;
+    }
+    // xterm sometimes leaves stale rows after a resize/replay; force a redraw.
+    function refreshRows() {
+        if (term.rows > 0)
+            term.refresh(0, term.rows - 1);
+    }
+    function sendResize() {
+        if (!socket || socket.readyState !== WebSocket.OPEN)
+            return;
+        if (term.cols === lastSentCols && term.rows === lastSentRows)
+            return;
+        lastSentCols = term.cols;
+        lastSentRows = term.rows;
+        socket.send(JSON.stringify({ type: 'resize', cols: term.cols, rows: term.rows }));
+    }
+    function fitNow() {
+        fit.fit();
+        sendResize();
+    }
+    function fitAndSendResize() {
+        window.requestAnimationFrame(() => {
+            fitNow();
+            refreshRows();
+        });
+    }
+    //
+    // Replay repaint repair (ported from threads): a replayed screen can render
+    // at a stale size; repaint across a microtask, two animation frames, and a
+    // couple of timers so the grid settles whatever the layout timing.
+    //
+    function clearReplayRepairWork() {
+        while (replayRepairFrames.length > 0) {
+            const frame = replayRepairFrames.pop();
+            if (frame !== undefined)
+                window.cancelAnimationFrame(frame);
+        }
+        while (replayRepairTimers.length > 0) {
+            const timer = replayRepairTimers.pop();
+            if (timer !== undefined)
+                window.clearTimeout(timer);
+        }
+    }
+    function repairReplayLayout() {
+        fitNow();
+        refreshRows();
+    }
+    function scheduleReplayRepair() {
+        clearReplayRepairWork();
+        window.queueMicrotask(repairReplayLayout);
+        replayRepairFrames.push(window.requestAnimationFrame(() => {
+            repairReplayLayout();
+            replayRepairFrames.push(window.requestAnimationFrame(repairReplayLayout));
+        }));
+        for (const delay of replayRepairDelaysMs) {
+            replayRepairTimers.push(window.setTimeout(repairReplayLayout, delay));
+        }
+    }
+    function handleMessage(msg) {
+        if (msg.type === 'replay') {
+            // Replay must land on a blank terminal, then repaint once layout settles.
+            term.reset();
+            term.write(forceTextSymbols(String(msg.data ?? '')), scheduleReplayRepair);
+        }
+        else if (msg.type === 'output') {
+            term.write(forceTextSymbols(String(msg.data ?? '')));
+        }
+        else if (msg.type === 'exit') {
+            reconnectEnabled = false;
+            clearReconnectTimer();
+        }
+    }
+    function scheduleReconnect() {
+        if (!reconnectEnabled)
+            return;
+        clearReconnectTimer();
+        if (document.visibilityState === 'hidden' || navigator.onLine === false)
+            return;
+        if (reconnectAttempt >= reconnectDelaysMs.length)
+            return;
+        const delay = reconnectDelaysMs[reconnectAttempt];
+        reconnectAttempt += 1;
+        reconnectTimer = window.setTimeout(connect, delay);
+    }
+    function connect() {
+        if (!reconnectEnabled)
+            return;
+        clearReconnectTimer();
+        if (document.visibilityState === 'hidden' || navigator.onLine === false)
+            return;
+        if (socket) {
+            intentionallyClosed.add(socket);
+            try {
+                socket.close(1000, 'reconnect');
+            }
+            catch {
+                /* ignore */
+            }
+        }
+        const ws = new WebSocket(wsUrl);
+        const token = ++socketToken;
+        socket = ws;
+        lastSentCols = 0;
+        lastSentRows = 0;
+        ws.addEventListener('open', () => {
+            if (socketToken !== token)
+                return;
+            reconnectAttempt = 0;
+            fitAndSendResize();
+        });
+        ws.addEventListener('message', (event) => {
+            if (socketToken !== token)
+                return;
+            try {
+                handleMessage(JSON.parse(String(event.data)));
+            }
+            catch {
+                /* ignore malformed frame */
+            }
+        });
+        ws.addEventListener('close', () => {
+            if (socketToken !== token)
+                return;
+            socket = null;
+            if (!reconnectEnabled || intentionallyClosed.has(ws))
+                return;
+            scheduleReconnect();
+        });
+        ws.addEventListener('error', () => {
+            /* the close handler drives reconnect */
+        });
+    }
+    //
+    // Wake handling: a backgrounded / offline tab drops its socket; reconnect as
+    // soon as it becomes visible, focused, or back online (ported from `ide`).
+    //
+    function wake(force) {
+        if (!activated || !reconnectEnabled || document.visibilityState === 'hidden')
+            return;
+        reconnectAttempt = 0;
+        if (socket && socket.readyState === WebSocket.OPEN) {
+            fitAndSendResize();
+            return;
+        }
+        if (socket && socket.readyState === WebSocket.CONNECTING)
+            return;
+        if (force || !socket || socket.readyState >= WebSocket.CLOSING)
+            connect();
+    }
+    document.addEventListener('visibilitychange', () => {
+        if (document.visibilityState === 'hidden') {
+            needsWakeReconnect = true;
+            clearReconnectTimer();
+            return;
+        }
+        const force = needsWakeReconnect;
+        needsWakeReconnect = false;
+        wake(force);
+    });
+    window.addEventListener('pagehide', () => {
+        needsWakeReconnect = true;
+        if (socket) {
+            intentionallyClosed.add(socket);
+            try {
+                socket.close(1000, 'page hidden');
+            }
+            catch {
+                /* ignore */
+            }
+        }
+        clearReconnectTimer();
+    });
+    window.addEventListener('pageshow', (event) => {
+        const force = needsWakeReconnect || event.persisted;
+        needsWakeReconnect = false;
+        wake(force);
+    });
+    window.addEventListener('focus', () => {
+        const force = needsWakeReconnect;
+        needsWakeReconnect = false;
+        wake(force);
+    });
+    window.addEventListener('offline', () => {
+        needsWakeReconnect = true;
+        clearReconnectTimer();
+    });
+    window.addEventListener('online', () => {
+        const force = needsWakeReconnect;
+        needsWakeReconnect = false;
+        wake(force);
+    });
+    // Send Ctrl+Enter as CSI 13;5u so claude/codex CLIs receive newline+modifier.
+    term.attachCustomKeyEventHandler((ev) => {
+        if (ev.type !== 'keydown')
+            return true;
+        if (ev.key === 'Enter' && ev.ctrlKey && !ev.shiftKey && !ev.altKey && !ev.metaKey) {
+            ev.preventDefault();
+            if (socket && socket.readyState === WebSocket.OPEN) {
+                socket.send(JSON.stringify({ type: 'input', data: '\x1b[13;5u' }));
+            }
+            return false;
+        }
+        return true;
+    });
+    term.onData((data) => {
+        if (socket && socket.readyState === WebSocket.OPEN) {
+            socket.send(JSON.stringify({ type: 'input', data }));
+        }
+    });
+    // Keep wheel scrolling inside the terminal -- don't chain to the host page
+    // when the viewport is at its top/bottom (or has nothing to scroll).
+    host.addEventListener('wheel', (event) => {
+        const viewport = host.querySelector('.xterm-viewport');
+        if (!viewport)
+            return;
+        const maxScrollTop = viewport.scrollHeight - viewport.clientHeight;
+        if (maxScrollTop <= 0) {
+            event.preventDefault();
+            return;
+        }
+        const pastTop = viewport.scrollTop <= 0 && event.deltaY < 0;
+        const pastBottom = viewport.scrollTop >= maxScrollTop - 1 && event.deltaY > 0;
+        if (pastTop || pastBottom)
+            event.preventDefault();
+    }, { passive: false });
+    const observer = new ResizeObserver(() => fitAndSendResize());
+    observer.observe(host);
+    // Restore the persisted open state: if the terminal was open last visit,
+    // reveal it and reconnect (re-attaching, or spawning, the pty).
+    if (storedOpen()) {
+        document.body.classList.add('term-open');
+        activateTerminal();
+    }
+    // Restore the persisted focus side. xterm needs a layout pass after
+    // term.open() before focus reliably lands on its helper textarea -- a
+    // synchronous focus here runs before xterm finishes mounting and silently
+    // fails. Defer the terminal-focus restore behind a fit + two animation
+    // frames so the grid has settled first (matching threads' post-layout
+    // focus sequencing).
+    if (storedFocus() === 'terminal' && document.body.classList.contains('term-open')) {
+        window.requestAnimationFrame(() => {
+            fitNow();
+            window.requestAnimationFrame(() => {
+                term.focus();
+            });
+        });
+    }
+    else if (deckFrame) {
+        deckFrame.contentWindow?.focus();
+    }
+})();
+export {};

package/dist/ide.d.ts

@@ -0,0 +1,16 @@
+import * as http from 'http';
+import { Duplex } from 'stream';
+export declare const IDE_ASSET_PREFIX = "/__castle/ide/";
+export declare const PTY_WS_PATH = "/__castle/pty";
+export declare const DECK_FOCUS_SCRIPT: string;
+export interface IdeServer {
+    /** Serve the IDE page + its static assets. Returns true if it handled the request. */
+    handleHttpRequest(req: http.IncomingMessage, res: http.ServerResponse, reqPath: string): boolean;
+    /** Attach the PTY WebSocket if the upgrade targets the PTY path. */
+    handleUpgrade(req: http.IncomingMessage, socket: Duplex, head: Buffer): boolean;
+    shutdown(): void;
+}
+export declare function createIdeServer(opts: {
+    deckDir: string;
+    deckLabel: string;
+}): IdeServer;