@dkkoval/tui-preview 0.1.1 → 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,46 +1,58 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useEffect, useMemo, useRef, useState } from "react";
-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 [termSize, setTermSize] = useState(resolved.fit === "container" ? null : resolved.size);
     useEffect(() => {
-        warnLegacyPropsOnce(resolved.usedLegacyProps);
-    }, [resolved.usedLegacyProps]);
-    useEffect(() => {
-        setTermSize(resolved.size);
+        setTermSize(resolved.fit === "container" ? null : resolved.size);
     }, [resolved.fit, resolved.size.cols, resolved.size.rows]);
     useEffect(() => {
         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.fit, resolved.terminal.fontSize]);
+    }, [resolved.fit, resolved.terminal.fontSize, resolved.terminal.fontFamily]);
     useEffect(() => {
         if (!termSize || !containerRef.current)
             return;
         let cancelled = false;
+        let disposeRenderSurface = null;
         const container = containerRef.current;
         const activeSize = termSize;
         const setStatusAndNotify = (next) => {
@@ -56,48 +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);
-                // Static mode: hide cursor via DEC PM — app output only, no cursor chrome.
-                if (resolved.mode === "static") {
-                    term.write("\x1b[?25l");
-                }
-                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");
@@ -105,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;
@@ -131,8 +139,8 @@ export function TuiPreview(props) {
         setup();
         return () => {
             cancelled = true;
-            termRef.current?.dispose();
-            termRef.current = null;
+            disposeRenderSurface?.();
+            disposeRenderSurface = null;
         };
     }, [
         resolved.mode,
@@ -148,12 +156,12 @@ export function TuiPreview(props) {
         resolved.terminal.fontSize,
         resolved.terminal.fontFamily,
         resolved.terminal.theme,
-        resolved.terminal.cursorBlink,
+        resolved.terminal.wasmUrl,
         resolved.terminal.convertEol,
     ]);
     return (_jsxs("div", { ref: wrapperRef, className: props.className, style: {
             position: "relative",
-            display: "inline-block",
+            display: resolved.fit === "container" ? "block" : "inline-block",
             background: resolved.terminal.theme?.background ?? "#1a1b26",
             borderRadius: 6,
             overflow: "hidden",

package/dist/core/index.d.ts

@@ -1,3 +1,3 @@
-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,3 +1,3 @@
-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 {};