@dkkoval/tui-preview 0.1.0 → 0.2.0

package/README.md

@@ -5,13 +5,27 @@ Render `wasm32-wasi` terminal apps inside React with a clean, size-aware API.
 ## Install
 
 ```bash
-npm install tui-preview
+npm install @dkkoval/tui-preview
 ```
 
+Build libghostty wasm from the submodule before running the example:
+
+```bash
+npm run build:ghostty-wasm
+```
+
+This builds an external wasm wrapper (`wasm/ghostty-vt/build.zig` + `wasm/ghostty-vt/wrapper.zig`)
+that imports Ghostty sources from `vendor/libghostty` without modifying submodule files.
+The wrapper is intentionally minimal: ANSI parsing + viewport rendering + basic input responses.
+
+By default this writes:
+- `example/public/ghostty-vt.wasm` (dev/example)
+- `dist/ghostty-vt.wasm` (library package asset)
+
 ## Modern API (v1)
 
 ```tsx
-import { TuiPreview } from "tui-preview";
+import { TuiPreview } from "@dkkoval/tui-preview";
 
 function Demo() {
   return (
@@ -48,31 +62,25 @@ function Demo() {
 - `argv?: string[] | ((size) => string[])`
   - CLI args (without argv[0]).
   - For `fit="container"`, size is the fitted terminal size.
+- `mode?: "interactive" | "static"` (default: `"interactive"`)
+  - `"interactive"`: keyboard/mouse-enabled terminal surface.
+  - `"static"`: non-interactive render surface.
 - `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 }`
+- `terminal?: { fontSize, fontFamily, theme, convertEol }`
+  - `terminal.wasmUrl?: string | URL` (default: `"/ghostty-vt.wasm"`)
 - `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.
+  - `@dkkoval/tui-preview` (React component + public types)
+  - `@dkkoval/tui-preview/core` (advanced internals)
+- libghostty source is tracked as a git submodule at `vendor/libghostty`.

package/dist/TuiPreview.js

@@ -1,55 +1,58 @@
 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 { createMiniTerminalSurface, measureCellSize } from "./core/libghostty.js";
+import { resolveTuiPreviewProps } 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);
+    const [termSize, setTermSize] = useState(resolved.fit === "container" ? null : resolved.size);
     useEffect(() => {
-        warnLegacyPropsOnce(resolved.usedLegacyProps);
-    }, [resolved.usedLegacyProps]);
-    // ── Terminal mode effects ────────────────────────────────────────────────
+        setTermSize(resolved.fit === "container" ? null : resolved.size);
+    }, [resolved.fit, resolved.size.cols, resolved.size.rows]);
     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 wrapper = wrapperRef.current;
+        const estimatedCell = measureCellSize(resolved.terminal.fontSize, resolved.terminal.fontFamily);
+        const updateFromPixels = (width, height) => {
+            const cellW = cellSizeRef.current?.w ?? estimatedCell.w;
+            const cellH = cellSizeRef.current?.h ?? estimatedCell.h;
+            const newCols = Math.max(1, Math.floor(width / cellW));
+            const newRows = Math.max(1, Math.floor(height / cellH));
+            setTermSize((prev) => {
+                if (prev && prev.cols === newCols && prev.rows === newRows)
+                    return prev;
+                return { cols: newCols, rows: newRows };
+            });
+        };
+        const rect = wrapper.getBoundingClientRect();
+        if (rect.width > 0 && rect.height > 0) {
+            updateFromPixels(rect.width, rect.height);
+        }
+        // Current fit strategy recalculates cols/rows from measured cell size and
+        // recreates the surface on size changes. This is acceptable for now, but
+        // an in-place resize path would be smoother for frequent container resizes.
         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)),
-                });
+                updateFromPixels(width, height);
             }
         });
-        observer.observe(wrapperRef.current);
+        observer.observe(wrapper);
         return () => observer.disconnect();
-    }, [resolved.mode, resolved.fit, resolved.terminal.fontSize]);
+    }, [resolved.fit, resolved.terminal.fontSize, resolved.terminal.fontFamily]);
     useEffect(() => {
-        if (resolved.mode !== "terminal")
-            return;
         if (!termSize || !containerRef.current)
             return;
         let cancelled = false;
+        let disposeRenderSurface = null;
         const container = containerRef.current;
         const activeSize = termSize;
         const setStatusAndNotify = (next) => {
@@ -65,44 +68,47 @@ export function TuiPreview(props) {
         setErrorMsg("");
         async function setup() {
             try {
-                const ghostty = await loadGhostty();
-                if (cancelled)
-                    return;
-                container.innerHTML = "";
-                const term = new ghostty.Terminal({
+                let appCols = activeSize.cols;
+                let appRows = activeSize.rows;
+                let bridge = null;
+                const surface = await createMiniTerminalSurface({
+                    container,
                     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,
+                    interactive: resolved.mode !== "static" && resolved.interactive,
+                    showCursor: resolved.mode !== "static",
+                    wasmUrl: resolved.terminal.wasmUrl,
+                    onInput: (data) => bridge?.pushInput(data),
                 });
-                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,
-                        };
-                    }
+                if (cancelled) {
+                    surface.dispose();
+                    return;
                 }
+                disposeRenderSurface = () => surface.dispose();
+                appCols = surface.cols;
+                appRows = surface.rows;
+                cellSizeRef.current = surface.cellSize;
                 const resolvedArgs = resolved.resolveArgv({ cols: appCols, rows: appRows });
-                const decoder = new TextDecoder();
-                const bridge = new WasiBridge({
+                const stdoutDecoder = new TextDecoder();
+                const stderrDecoder = new TextDecoder();
+                const flushSurfaceOutput = (data, decoder) => {
+                    const decoded = decoder.decode(data, { stream: true });
+                    if (decoded) {
+                        surface.write(decoded);
+                    }
+                    for (const response of surface.drainResponses()) {
+                        bridge?.pushInput(response);
+                    }
+                };
+                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)),
+                    stdout: (data) => flushSurfaceOutput(data, stdoutDecoder),
+                    stderr: (data) => flushSurfaceOutput(data, stderrDecoder),
                     onExit: (code) => {
                         if (!cancelled) {
                             setStatusAndNotify("exited");
@@ -110,9 +116,6 @@ export function TuiPreview(props) {
                         }
                     },
                 });
-                if (resolved.interactive) {
-                    term.onData((data) => bridge.pushInput(data));
-                }
                 const wasmApp = await instantiateApp(resolved.wasm, bridge);
                 if (cancelled)
                     return;
@@ -136,8 +139,8 @@ export function TuiPreview(props) {
         setup();
         return () => {
             cancelled = true;
-            termRef.current?.dispose();
-            termRef.current = null;
+            disposeRenderSurface?.();
+            disposeRenderSurface = null;
         };
     }, [
         resolved.mode,
@@ -153,97 +156,13 @@ export function TuiPreview(props) {
         resolved.terminal.fontSize,
         resolved.terminal.fontFamily,
         resolved.terminal.theme,
-        resolved.terminal.cursorBlink,
+        resolved.terminal.wasmUrl,
         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,
+            display: resolved.fit === "container" ? "block" : "inline-block",
+            background: resolved.terminal.theme?.background ?? "#1a1b26",
             borderRadius: 6,
             overflow: "hidden",
             ...props.style,

package/dist/core/index.d.ts

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

package/dist/core/index.js

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

package/dist/core/libghostty.d.ts

@@ -0,0 +1,86 @@
+import type { GhosttyTheme } from "../types.js";
+interface LibGhosttyExports extends WebAssembly.Exports {
+    memory: WebAssembly.Memory;
+    ghostty_wasm_alloc_u8_array(len: number): number;
+    ghostty_wasm_free_u8_array(ptr: number, len: number): void;
+    ghostty_terminal_new(cols: number, rows: number): number;
+    ghostty_terminal_new_with_config(cols: number, rows: number, configPtr: number): number;
+    ghostty_terminal_free(handle: number): void;
+    ghostty_terminal_resize(handle: number, cols: number, rows: number): void;
+    ghostty_terminal_write(handle: number, dataPtr: number, dataLen: number): void;
+    ghostty_render_state_update(handle: number): number;
+    ghostty_render_state_get_cols(handle: number): number;
+    ghostty_render_state_get_rows(handle: number): number;
+    ghostty_render_state_is_row_dirty(handle: number, row: number): boolean;
+    ghostty_render_state_mark_clean(handle: number): void;
+    ghostty_render_state_get_viewport(handle: number, bufPtr: number, bufLen: number): number;
+    ghostty_terminal_has_response(handle: number): boolean;
+    ghostty_terminal_read_response(handle: number, bufPtr: number, bufLen: number): number;
+}
+export interface MiniTerminalSurfaceOptions {
+    container: HTMLElement;
+    /** Explicit cell dimensions — used directly when provided. */
+    cols?: number;
+    rows?: number;
+    /** Pixel dimensions — if provided, cols/rows are computed from font metrics. */
+    widthPx?: number;
+    heightPx?: number;
+    fontSize: number;
+    fontFamily: string;
+    theme?: Partial<GhosttyTheme>;
+    convertEol: boolean;
+    interactive: boolean;
+    showCursor: boolean;
+    onInput?: (data: string) => void;
+    wasmUrl?: string | URL;
+}
+export interface MiniTerminalSurface {
+    cols: number;
+    rows: number;
+    cellSize: {
+        w: number;
+        h: number;
+    };
+    write(text: string): void;
+    drainResponses(): string[];
+    dispose(): void;
+}
+declare class LibGhosttyRuntime {
+    private readonly wasm;
+    private readonly abi;
+    constructor(wasm: LibGhosttyExports, abi: {
+        cellSize: number;
+        terminalConfigSize: number;
+    });
+    createTerminal(cols: number, rows: number, theme: GhosttyTheme): LibGhosttyTerminal;
+}
+declare class LibGhosttyTerminal {
+    private readonly wasm;
+    private readonly handle;
+    cols: number;
+    rows: number;
+    private readonly cellSize;
+    private viewportPtr;
+    private viewportLen;
+    constructor(wasm: LibGhosttyExports, handle: number, cols: number, rows: number, cellSize: number);
+    write(textOrData: string | Uint8Array): void;
+    resize(cols: number, rows: number): void;
+    hasResponse(): boolean;
+    isDirty(): boolean;
+    readResponse(maxBytes?: number): string | null;
+    getViewportData(): {
+        cols: number;
+        rows: number;
+        buffer: Uint8Array;
+    };
+    dispose(): void;
+    private releaseViewport;
+}
+/** Measure monospace cell size for a given font. Cheap and synchronous. */
+export declare function measureCellSize(fontSize: number, fontFamily: string): {
+    w: number;
+    h: number;
+};
+export declare function loadLibGhostty(wasmUrl?: string | URL): Promise<LibGhosttyRuntime>;
+export declare function createMiniTerminalSurface(options: MiniTerminalSurfaceOptions): Promise<MiniTerminalSurface>;
+export {};