@dkkoval/tui-preview 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 tui-preview contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,78 @@
+# tui-preview
+
+Render `wasm32-wasi` terminal apps inside React with a clean, size-aware API.
+
+## Install
+
+```bash
+npm install tui-preview
+```
+
+## Modern API (v1)
+
+```tsx
+import { TuiPreview } from "tui-preview";
+
+function Demo() {
+  return (
+    <TuiPreview
+      wasm={new URL("./gradient.wasm", import.meta.url)}
+      argv={({ cols, rows }) => [
+        "Hello!",
+        String(cols),
+        String(Math.max(1, rows - 1)),
+        "--gradient",
+        "diagonal",
+        "--no-border",
+      ]}
+      fit="container"
+      terminal={{
+        fontSize: 14,
+        fontFamily: "monospace",
+        theme: {
+          background: "#1a1b26",
+          foreground: "#a9b1d6",
+        },
+      }}
+      interactive
+      style={{ width: "100%", height: 400 }}
+    />
+  );
+}
+```
+
+## API
+
+- `wasm: string | URL`
+  - WASM entrypoint compiled for `wasm32-wasi`.
+- `argv?: string[] | ((size) => string[])`
+  - CLI args (without argv[0]).
+  - For `fit="container"`, size is the fitted terminal size.
+- `fit?: "container" | "none"` (default: `"container"`)
+  - `"container"`: auto-size from container.
+  - `"none"`: fixed terminal size from `size`.
+- `size?: { cols: number; rows: number }`
+  - Required in practice for fixed mode; fallback/initial for container mode.
+- `terminal?: { fontSize, fontFamily, theme, cursorBlink, convertEol }`
+- `interactive?: boolean` (default: `true`)
+- `env?: Record<string, string>`
+- `onExit?: (code: number) => void`
+- `onError?: (error: unknown) => void`
+- `onStatusChange?: ("loading" | "running" | "exited" | "error") => void`
+
+## Legacy Compatibility
+
+Legacy props still work:
+
+- `app`, `args`
+- `cols`, `rows`
+- `fontSize`, `fontFamily`, `theme`
+
+They are translated internally to the modern API and emit a one-time deprecation warning.
+
+## Notes
+
+- Package exports:
+  - `tui-preview` (React component + public types)
+  - `tui-preview/core` (advanced internals)
+- `ghostty-web` is pinned with semver (`^0.4.0`) for predictable behavior.

package/dist/TuiPreview.d.ts

@@ -0,0 +1,2 @@
+import type { TuiPreviewProps } from "./types.js";
+export declare function TuiPreview(props: TuiPreviewProps): import("react/jsx-runtime").JSX.Element;

package/dist/TuiPreview.js

@@ -0,0 +1,257 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useMemo, useRef, useState } from "react";
+import { ansiToHtml } from "./core/ansi.js";
+import { loadGhostty } from "./core/ghostty.js";
+import { resolveTuiPreviewProps, warnLegacyPropsOnce } from "./core/normalize.js";
+import { WasiBridge, instantiateApp } from "./core/wasi.js";
+export function TuiPreview(props) {
+    const resolved = useMemo(() => resolveTuiPreviewProps(props), [props]);
+    const wrapperRef = useRef(null);
+    const containerRef = useRef(null);
+    const termRef = useRef(null);
+    const [status, setStatus] = useState("loading");
+    const [errorMsg, setErrorMsg] = useState("");
+    const cellSizeRef = useRef(null);
+    const [termSize, setTermSize] = useState(resolved.size);
+    const [staticHtml, setStaticHtml] = useState(null);
+    useEffect(() => {
+        warnLegacyPropsOnce(resolved.usedLegacyProps);
+    }, [resolved.usedLegacyProps]);
+    // ── Terminal mode effects ────────────────────────────────────────────────
+    useEffect(() => {
+        if (resolved.mode !== "terminal")
+            return;
+        setTermSize(resolved.size);
+    }, [resolved.mode, resolved.fit, resolved.size.cols, resolved.size.rows]);
+    useEffect(() => {
+        if (resolved.mode !== "terminal")
+            return;
+        if (resolved.fit !== "container")
+            return;
+        if (!wrapperRef.current)
+            return;
+        const observer = new ResizeObserver(([entry]) => {
+            const { width, height } = entry.contentRect;
+            if (width > 0 && height > 0) {
+                const cellW = cellSizeRef.current?.w ?? resolved.terminal.fontSize * 0.6;
+                const cellH = cellSizeRef.current?.h ?? resolved.terminal.fontSize * 1.2;
+                setTermSize({
+                    cols: Math.max(1, Math.floor(width / cellW)),
+                    rows: Math.max(1, Math.floor(height / cellH)),
+                });
+            }
+        });
+        observer.observe(wrapperRef.current);
+        return () => observer.disconnect();
+    }, [resolved.mode, resolved.fit, resolved.terminal.fontSize]);
+    useEffect(() => {
+        if (resolved.mode !== "terminal")
+            return;
+        if (!termSize || !containerRef.current)
+            return;
+        let cancelled = false;
+        const container = containerRef.current;
+        const activeSize = termSize;
+        const setStatusAndNotify = (next) => {
+            setStatus(next);
+            resolved.onStatusChange?.(next);
+        };
+        const setError = (err) => {
+            setStatusAndNotify("error");
+            setErrorMsg(err instanceof Error ? err.message : String(err));
+            resolved.onError?.(err);
+        };
+        setStatusAndNotify("loading");
+        setErrorMsg("");
+        async function setup() {
+            try {
+                const ghostty = await loadGhostty();
+                if (cancelled)
+                    return;
+                container.innerHTML = "";
+                const term = new ghostty.Terminal({
+                    cols: activeSize.cols,
+                    rows: activeSize.rows,
+                    fontSize: resolved.terminal.fontSize,
+                    fontFamily: resolved.terminal.fontFamily,
+                    theme: resolved.terminal.theme,
+                    disableStdin: !resolved.interactive,
+                    cursorBlink: resolved.terminal.cursorBlink,
+                    convertEol: resolved.terminal.convertEol,
+                });
+                termRef.current = term;
+                term.open(container);
+                let appCols = term.cols;
+                let appRows = term.rows;
+                if (resolved.fit === "container") {
+                    const fitAddon = new ghostty.FitAddon();
+                    term.loadAddon(fitAddon);
+                    fitAddon.fit();
+                    appCols = term.cols;
+                    appRows = term.rows;
+                    if (wrapperRef.current && appCols > 0 && appRows > 0) {
+                        cellSizeRef.current = {
+                            w: wrapperRef.current.clientWidth / appCols,
+                            h: wrapperRef.current.clientHeight / appRows,
+                        };
+                    }
+                }
+                const resolvedArgs = resolved.resolveArgv({ cols: appCols, rows: appRows });
+                const decoder = new TextDecoder();
+                const bridge = new WasiBridge({
+                    args: [resolved.wasm.toString(), ...resolvedArgs],
+                    env: resolved.env,
+                    stdout: (data) => term.write(decoder.decode(data)),
+                    stderr: (data) => term.write(decoder.decode(data)),
+                    onExit: (code) => {
+                        if (!cancelled) {
+                            setStatusAndNotify("exited");
+                            resolved.onExit?.(code);
+                        }
+                    },
+                });
+                if (resolved.interactive) {
+                    term.onData((data) => bridge.pushInput(data));
+                }
+                const wasmApp = await instantiateApp(resolved.wasm, bridge);
+                if (cancelled)
+                    return;
+                setStatusAndNotify("running");
+                queueMicrotask(() => {
+                    if (cancelled)
+                        return;
+                    void wasmApp.run().catch((runError) => {
+                        if (!cancelled) {
+                            setError(runError);
+                        }
+                    });
+                });
+            }
+            catch (e) {
+                if (!cancelled) {
+                    setError(e);
+                }
+            }
+        }
+        setup();
+        return () => {
+            cancelled = true;
+            termRef.current?.dispose();
+            termRef.current = null;
+        };
+    }, [
+        resolved.mode,
+        termSize,
+        resolved.wasm,
+        resolved.resolveArgv,
+        resolved.env,
+        resolved.fit,
+        resolved.interactive,
+        resolved.onExit,
+        resolved.onError,
+        resolved.onStatusChange,
+        resolved.terminal.fontSize,
+        resolved.terminal.fontFamily,
+        resolved.terminal.theme,
+        resolved.terminal.cursorBlink,
+        resolved.terminal.convertEol,
+    ]);
+    // ── Static mode effect ───────────────────────────────────────────────────
+    useEffect(() => {
+        if (resolved.mode !== "static")
+            return;
+        let cancelled = false;
+        const setStatusAndNotify = (next) => {
+            setStatus(next);
+            resolved.onStatusChange?.(next);
+        };
+        setStatusAndNotify("loading");
+        setErrorMsg("");
+        setStaticHtml(null);
+        async function run() {
+            try {
+                const decoder = new TextDecoder();
+                const chunks = [];
+                const bridge = new WasiBridge({
+                    args: [resolved.wasm.toString(), ...resolved.resolveArgv(resolved.size)],
+                    env: resolved.env,
+                    stdout: (data) => chunks.push(new Uint8Array(data)),
+                    stderr: () => { },
+                    onExit: (code) => {
+                        if (!cancelled) {
+                            const total = chunks.reduce((n, c) => n + c.length, 0);
+                            const merged = new Uint8Array(total);
+                            let offset = 0;
+                            for (const c of chunks) {
+                                merged.set(c, offset);
+                                offset += c.length;
+                            }
+                            setStaticHtml(ansiToHtml(decoder.decode(merged)));
+                            setStatusAndNotify("exited");
+                            resolved.onExit?.(code);
+                        }
+                    },
+                });
+                const wasmApp = await instantiateApp(resolved.wasm, bridge);
+                if (cancelled)
+                    return;
+                setStatusAndNotify("running");
+                await wasmApp.run();
+            }
+            catch (e) {
+                if (!cancelled) {
+                    setStatusAndNotify("error");
+                    setErrorMsg(e instanceof Error ? e.message : String(e));
+                    resolved.onError?.(e);
+                }
+            }
+        }
+        run();
+        return () => { cancelled = true; };
+    }, [
+        resolved.mode,
+        resolved.wasm,
+        resolved.resolveArgv,
+        resolved.env,
+        resolved.size.cols,
+        resolved.size.rows,
+        resolved.onExit,
+        resolved.onError,
+        resolved.onStatusChange,
+    ]);
+    // ── Render ───────────────────────────────────────────────────────────────
+    const bg = resolved.terminal.theme?.background ?? "#1a1b26";
+    const fg = resolved.terminal.theme?.foreground ?? "#a9b1d6";
+    if (resolved.mode === "static") {
+        return (_jsxs("div", { className: props.className, style: {
+                position: "relative",
+                background: bg,
+                borderRadius: 6,
+                overflow: "hidden",
+                ...props.style,
+            }, children: [status === "loading" && _jsx("div", { style: overlayStyle, children: "Loading\u2026" }), status === "error" && (_jsxs("div", { style: { ...overlayStyle, color: "#f7768e" }, children: ["Error: ", errorMsg] })), staticHtml !== null && (_jsx("pre", { style: {
+                        margin: 0,
+                        padding: "0.5em",
+                        fontFamily: resolved.terminal.fontFamily,
+                        fontSize: resolved.terminal.fontSize,
+                        color: fg,
+                        lineHeight: 1.2,
+                        background: "transparent",
+                        overflow: "auto",
+                    }, dangerouslySetInnerHTML: { __html: staticHtml } }))] }));
+    }
+    return (_jsxs("div", { ref: wrapperRef, className: props.className, style: {
+            position: "relative",
+            display: "inline-block",
+            background: bg,
+            borderRadius: 6,
+            overflow: "hidden",
+            ...props.style,
+        }, children: [_jsx("div", { ref: containerRef, style: { display: status === "error" ? "none" : undefined } }), status === "loading" && (_jsx("div", { style: overlayStyle, children: "Loading\u2026" })), status === "error" && (_jsxs("div", { style: { ...overlayStyle, color: "#f7768e" }, children: ["Error: ", errorMsg] }))] }));
+}
+const overlayStyle = {
+    padding: "1rem",
+    fontFamily: "monospace",
+    fontSize: 14,
+    color: "#a9b1d6",
+};

package/dist/__vite-browser-external-2447137e-BcPniuRQ.cjs

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const e={};exports.default=e;

package/dist/__vite-browser-external-2447137e-DYxpcVy9.js

@@ -0,0 +1,4 @@
+const e = {};
+export {
+  e as default
+};

package/dist/core/ansi.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Minimal ANSI SGR → HTML converter.
+ *
+ * Handles the subset used by typical wasm32-wasi TUI apps:
+ *   - Reset (0)
+ *   - Bold, italic, underline (1/3/4 and their off codes)
+ *   - Standard 16-color fg/bg (30–37, 39, 40–47, 49, 90–97, 100–107)
+ *   - 256-color fg/bg (38;5;N / 48;5;N)
+ *   - 24-bit truecolor fg/bg (38;2;R;G;B / 48;2;R;G;B)
+ *
+ * Non-SGR CSI sequences (cursor movement etc.) are silently dropped,
+ * which is correct for static capture where only the final text matters.
+ */
+/** Convert ANSI escape codes to an HTML string of styled `<span>` elements. */
+export declare function ansiToHtml(input: string): string;

package/dist/core/ansi.js

@@ -0,0 +1,181 @@
+/**
+ * Minimal ANSI SGR → HTML converter.
+ *
+ * Handles the subset used by typical wasm32-wasi TUI apps:
+ *   - Reset (0)
+ *   - Bold, italic, underline (1/3/4 and their off codes)
+ *   - Standard 16-color fg/bg (30–37, 39, 40–47, 49, 90–97, 100–107)
+ *   - 256-color fg/bg (38;5;N / 48;5;N)
+ *   - 24-bit truecolor fg/bg (38;2;R;G;B / 48;2;R;G;B)
+ *
+ * Non-SGR CSI sequences (cursor movement etc.) are silently dropped,
+ * which is correct for static capture where only the final text matters.
+ */
+// Standard xterm 16-color palette
+const ANSI16 = [
+    "#000000", "#cd0000", "#00cd00", "#cdcd00",
+    "#0000ee", "#cd00cd", "#00cdcd", "#e5e5e5",
+    "#7f7f7f", "#ff0000", "#00ff00", "#ffff00",
+    "#5c5cff", "#ff00ff", "#00ffff", "#ffffff",
+];
+function color256(n) {
+    if (n < 16)
+        return ANSI16[n];
+    if (n < 232) {
+        const i = n - 16;
+        const r = Math.floor(i / 36);
+        const g = Math.floor((i % 36) / 6);
+        const b = i % 6;
+        const v = (x) => (x === 0 ? 0 : x * 40 + 55);
+        return `rgb(${v(r)},${v(g)},${v(b)})`;
+    }
+    const grey = (n - 232) * 10 + 8;
+    return `rgb(${grey},${grey},${grey})`;
+}
+function escHtml(s) {
+    return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+/** Convert ANSI escape codes to an HTML string of styled `<span>` elements. */
+export function ansiToHtml(input) {
+    // Current SGR state
+    let fg = null;
+    let bg = null;
+    let bold = false;
+    let italic = false;
+    let underline = false;
+    const result = [];
+    let buf = "";
+    let bufStyle = "";
+    function buildStyle() {
+        const parts = [];
+        if (fg)
+            parts.push(`color:${fg}`);
+        if (bg)
+            parts.push(`background-color:${bg}`);
+        if (bold)
+            parts.push("font-weight:bold");
+        if (italic)
+            parts.push("font-style:italic");
+        if (underline)
+            parts.push("text-decoration:underline");
+        return parts.join(";");
+    }
+    function flush() {
+        if (!buf)
+            return;
+        result.push(bufStyle ? `<span style="${bufStyle}">${escHtml(buf)}</span>` : escHtml(buf));
+        buf = "";
+    }
+    function applySgr(params) {
+        flush();
+        let i = 0;
+        while (i < params.length) {
+            const p = params[i];
+            if (p === 0) {
+                fg = null;
+                bg = null;
+                bold = false;
+                italic = false;
+                underline = false;
+            }
+            else if (p === 1) {
+                bold = true;
+            }
+            else if (p === 22) {
+                bold = false;
+            }
+            else if (p === 3) {
+                italic = true;
+            }
+            else if (p === 23) {
+                italic = false;
+            }
+            else if (p === 4) {
+                underline = true;
+            }
+            else if (p === 24) {
+                underline = false;
+            }
+            else if (p >= 30 && p <= 37) {
+                fg = ANSI16[p - 30];
+            }
+            else if (p === 38) {
+                if (params[i + 1] === 2 && i + 4 < params.length) {
+                    fg = `rgb(${params[i + 2]},${params[i + 3]},${params[i + 4]})`;
+                    i += 4;
+                }
+                else if (params[i + 1] === 5 && i + 2 < params.length) {
+                    fg = color256(params[i + 2]);
+                    i += 2;
+                }
+            }
+            else if (p === 39) {
+                fg = null;
+            }
+            else if (p >= 40 && p <= 47) {
+                bg = ANSI16[p - 40];
+            }
+            else if (p === 48) {
+                if (params[i + 1] === 2 && i + 4 < params.length) {
+                    bg = `rgb(${params[i + 2]},${params[i + 3]},${params[i + 4]})`;
+                    i += 4;
+                }
+                else if (params[i + 1] === 5 && i + 2 < params.length) {
+                    bg = color256(params[i + 2]);
+                    i += 2;
+                }
+            }
+            else if (p === 49) {
+                bg = null;
+            }
+            else if (p >= 90 && p <= 97) {
+                fg = ANSI16[p - 82];
+            }
+            else if (p >= 100 && p <= 107) {
+                bg = ANSI16[p - 92];
+            }
+            i++;
+        }
+        bufStyle = buildStyle();
+    }
+    let i = 0;
+    while (i < input.length) {
+        const ch = input[i];
+        if (ch === "\x1b" && i + 1 < input.length && input[i + 1] === "[") {
+            // CSI sequence: find the final byte (0x40–0x7e)
+            const seqStart = i + 2;
+            let end = seqStart;
+            while (end < input.length && (input.charCodeAt(end) < 0x40 || input.charCodeAt(end) > 0x7e)) {
+                end++;
+            }
+            if (end < input.length) {
+                if (input[end] === "m") {
+                    const seq = input.slice(seqStart, end);
+                    const params = seq ? seq.split(";").map((s) => parseInt(s, 10) || 0) : [0];
+                    applySgr(params);
+                }
+                // Non-SGR CSI (cursor movement etc.) — silently skip
+                i = end + 1;
+            }
+            else {
+                // Incomplete sequence at end of input — skip escape char
+                i++;
+            }
+        }
+        else if (ch === "\r") {
+            i++;
+        }
+        else {
+            // Regular character — append, flushing if style changed
+            const style = buildStyle();
+            if (style !== bufStyle) {
+                flush();
+                bufStyle = style;
+            }
+            buf += ch;
+            i++;
+        }
+    }
+    flush();
+    return result.join("");
+}

package/dist/core/ghostty.d.ts

@@ -0,0 +1,2 @@
+/** Load ghostty-web lazily to avoid SSR issues in host apps. */
+export declare function loadGhostty(): Promise<typeof import("ghostty-web")>;

package/dist/core/ghostty.js

@@ -0,0 +1,11 @@
+let ghosttyReady = null;
+/** Load ghostty-web lazily to avoid SSR issues in host apps. */
+export function loadGhostty() {
+    if (!ghosttyReady) {
+        ghosttyReady = import("ghostty-web").then(async (mod) => {
+            await mod.init();
+            return mod;
+        });
+    }
+    return ghosttyReady;
+}

package/dist/core/index.d.ts

@@ -0,0 +1,4 @@
+export { ansiToHtml } from "./ansi.js";
+export { loadGhostty } from "./ghostty.js";
+export { resolveTuiPreviewProps, warnLegacyPropsOnce } from "./normalize.js";
+export { WasiBridge, WasiExitError, instantiateApp } from "./wasi.js";

package/dist/core/index.js

@@ -0,0 +1,4 @@
+export { ansiToHtml } from "./ansi.js";
+export { loadGhostty } from "./ghostty.js";
+export { resolveTuiPreviewProps, warnLegacyPropsOnce } from "./normalize.js";
+export { WasiBridge, WasiExitError, instantiateApp } from "./wasi.js";

package/dist/core/normalize.d.ts

@@ -0,0 +1,3 @@
+import type { ResolvedTuiPreviewOptions, TuiPreviewProps } from "../types.js";
+export declare function warnLegacyPropsOnce(usedLegacyProps: boolean): void;
+export declare function resolveTuiPreviewProps(props: TuiPreviewProps): ResolvedTuiPreviewOptions;