@adecore/terminal 0.0.0-stage → 0.15.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bas Milius
+
+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

@@ -1,3 +1,39 @@
-# Temporary Holding Version
+# @adecore/terminal
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![npm](https://img.shields.io/npm/v/@adecore/terminal)](https://www.npmjs.com/package/@adecore/terminal)
+[![Docs](https://img.shields.io/badge/docs-adecore.dev-blue)](https://adecore.dev/terminal/)
+
+A terminal pane on [xterm.js](https://xtermjs.org) that looks like the rest of an `@adecore/ui` interface in both themes. It fits the box it is given, opens links in the output and either takes typing or only shows output. The app feeds it output and reads back what is on screen through a handle, without touching xterm's addons.
+
+**[Documentation](https://adecore.dev/terminal/)**
+
+## Install
+
+```sh
+bun add @adecore/terminal @xterm/xterm @xterm/addon-fit @xterm/addon-web-links @xterm/addon-webgl
+```
+
+xterm and its addons are peer dependencies, so the app picks the version. Import xterm's stylesheet and this package's after the theme of `@adecore/ui`:
+
+```css
+@import "tailwindcss";
+@import "@adecore/ui/theme.css";
+@import "@xterm/xterm/css/xterm.css";
+@import "@adecore/terminal/terminal.css";
+```
+
+## Use
+
+```tsx
+import { TerminalView, type TerminalViewHandle } from '@adecore/terminal';
+
+const view = useRef<TerminalViewHandle>(null);
+
+useEffect(() => session.onOutput((data) => view.current?.write(data)), [session]);
+
+<TerminalView ref={view} label="Shell" onData={(data) => session.write(data)} onResize={(cols, rows) => session.resize(cols, rows)} className="h-full" />
+```
+
+## License
+
+MIT

package/dist/TerminalView.d.ts

@@ -0,0 +1,34 @@
+import { type Ref } from 'react';
+import { Terminal } from '@xterm/xterm';
+export interface TerminalSize {
+    cols: number;
+    rows: number;
+}
+export interface TerminalViewHandle {
+    readonly terminal: Terminal | null;
+    write(data: string, done?: () => void): void;
+    reset(): void;
+    focus(): void;
+    blur(): void;
+    paste(text: string): void;
+    selectAll(): void;
+    selection(): string;
+    size(): TerminalSize;
+    visibleText(): string;
+    followGrid(size: TerminalSize): void;
+}
+export interface TerminalViewProps {
+    ref?: Ref<TerminalViewHandle>;
+    onData?(data: string): void;
+    onResize?(cols: number, rows: number): void;
+    onOpenLink?(uri: string): void;
+    fontSize?: number;
+    lineHeight?: number;
+    readOnly?: boolean;
+    convertEol?: boolean;
+    webgl?: boolean;
+    scaledByAncestor?: boolean;
+    label?: string;
+    className?: string;
+}
+export declare function TerminalView({ ref, onData, onResize, onOpenLink, fontSize, lineHeight, readOnly, convertEol, webgl, scaledByAncestor, label, className }: TerminalViewProps): import("react").JSX.Element;

package/dist/TerminalView.js

@@ -0,0 +1,196 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useEffect, useImperativeHandle, useRef } from 'react';
+import clsx from 'clsx';
+import { FitAddon } from '@xterm/addon-fit';
+import { WebLinksAddon } from '@xterm/addon-web-links';
+import { Terminal } from '@xterm/xterm';
+import { readTerminalFont, readTerminalTheme } from './theme.js';
+import { webglBudget } from './webgl-budget.js';
+import { fitToHost, followAncestorScale } from './xterm-internals.js';
+const RESIZE_DEBOUNCE_MS = 50;
+/* What the theme and the font are read from: the theme attribute and the tokens an app sets inline on `<html>`. */
+const ROOT_ATTRIBUTES = ['data-theme', 'style', 'class'];
+let terminals = 0;
+/* A terminal on xterm.js that fits its container and follows the theme. The app feeds it through the handle. */
+export function TerminalView({ ref, onData, onResize, onOpenLink, fontSize = 13, lineHeight = 1, readOnly = false, convertEol = false, webgl = false, scaledByAncestor = false, label, className }) {
+    const hostRef = useRef(null);
+    const live = useRef(null);
+    // Filled with the first props, so the mount reads them before the effect below brings them up to date.
+    const latest = useRef({ onData, onResize, onOpenLink, fontSize, lineHeight, scaledByAncestor });
+    useEffect(() => {
+        latest.current = { onData, onResize, onOpenLink, fontSize, lineHeight, scaledByAncestor };
+    });
+    useImperativeHandle(ref, () => ({
+        get terminal() {
+            return live.current?.term ?? null;
+        },
+        write: (data, done) => {
+            const current = live.current;
+            if (!current) {
+                return;
+            }
+            current.term.write(data, done);
+            if (current.webgl) {
+                // A terminal that is being written to outranks an idle one when contexts are scarce.
+                webglBudget.touch(current.id);
+            }
+        },
+        // Through the parser (RIS), since `Terminal.reset()` runs at once and output still queued would land on the fresh screen.
+        reset: () => live.current?.term.write('\x1bc'),
+        focus: () => {
+            live.current?.term.focus();
+            if (live.current?.webgl) {
+                webglBudget.focus(live.current.id);
+            }
+        },
+        blur: () => {
+            live.current?.term.blur();
+            if (live.current?.webgl) {
+                webglBudget.blur(live.current.id);
+            }
+        },
+        paste: (text) => live.current?.term.paste(text),
+        selectAll: () => live.current?.term.selectAll(),
+        selection: () => live.current?.term.getSelection() ?? '',
+        size: () => ({ cols: live.current?.term.cols ?? 80, rows: live.current?.term.rows ?? 24 }),
+        visibleText: () => {
+            const term = live.current?.term;
+            if (!term) {
+                return '';
+            }
+            const buffer = term.buffer.active;
+            const lines = [];
+            for (let row = 0; row < term.rows; row++) {
+                lines.push(buffer.getLine(buffer.viewportY + row)?.translateToString(true) ?? '');
+            }
+            return lines.join('\n').replace(/\s+$/, '');
+        },
+        followGrid: (size) => live.current?.followGrid(size)
+    }), []);
+    useEffect(() => {
+        const host = hostRef.current;
+        if (!host) {
+            return;
+        }
+        const initial = latest.current;
+        const term = new Terminal({
+            theme: readTerminalTheme(),
+            fontFamily: readTerminalFont(),
+            fontSize: initial.fontSize,
+            lineHeight: initial.lineHeight,
+            cursorBlink: true,
+            scrollback: 5000,
+            macOptionIsMeta: true
+        });
+        const fit = new FitAddon();
+        term.loadAddon(fit);
+        term.loadAddon(new WebLinksAddon(latest.current.onOpenLink ? (_event, uri) => latest.current.onOpenLink?.(uri) : undefined));
+        term.open(host);
+        if (initial.scaledByAncestor) {
+            followAncestorScale(term);
+        }
+        fitToHost(term, fit);
+        /*
+         * The grid this terminal fits and tells the program, and the grid the program has. They part while
+         * another client sizes the same program; this one then draws that grid, clipped or with room to
+         * spare, until a fit here changes the grid and claims it back.
+         */
+        let claimed = { cols: term.cols, rows: term.rows };
+        let shared = claimed;
+        const drawShared = () => {
+            if (term.cols !== shared.cols || term.rows !== shared.rows) {
+                term.resize(shared.cols, shared.rows);
+            }
+        };
+        // A resize, a font change and a renderer swap all land here: WebGL and the DOM measure a glyph
+        // differently, so a swap can change how many cells fit.
+        const refit = () => {
+            fitToHost(term, fit);
+            if (term.cols !== claimed.cols || term.rows !== claimed.rows) {
+                claimed = { cols: term.cols, rows: term.rows };
+                shared = claimed;
+                latest.current.onResize?.(claimed.cols, claimed.rows);
+            }
+            drawShared();
+        };
+        let theme = JSON.stringify(term.options.theme);
+        const restyle = (size, height) => {
+            const next = readTerminalTheme();
+            // A fresh theme object repaints every cell, so only a different one is handed over.
+            if (JSON.stringify(next) !== theme) {
+                theme = JSON.stringify(next);
+                term.options.theme = next;
+            }
+            term.options.fontFamily = readTerminalFont();
+            term.options.fontSize = size;
+            term.options.lineHeight = height;
+            // A new glyph size changes how many cells fit; the resize observer only hears the host.
+            refit();
+        };
+        const id = `terminal-${++terminals}`;
+        let releaseWebgl = null;
+        const current = {
+            term,
+            refit,
+            restyle,
+            followGrid: (size) => {
+                shared = size;
+                drawShared();
+            },
+            setInput: (readOnly, convertEol) => {
+                term.options.disableStdin = readOnly;
+                term.options.cursorBlink = !readOnly;
+                term.options.convertEol = convertEol;
+            },
+            setWebgl: (on) => {
+                current.webgl = on;
+                if (on && releaseWebgl === null) {
+                    releaseWebgl = webglBudget.register(id, term, refit);
+                }
+                else if (!on && releaseWebgl !== null) {
+                    releaseWebgl();
+                    releaseWebgl = null;
+                }
+            },
+            webgl: false,
+            id
+        };
+        live.current = current;
+        const data = term.onData((input) => latest.current.onData?.(input));
+        let timer = null;
+        const resizes = new ResizeObserver(() => {
+            if (timer !== null) {
+                window.clearTimeout(timer);
+            }
+            timer = window.setTimeout(() => {
+                timer = null;
+                refit();
+            }, RESIZE_DEBOUNCE_MS);
+        });
+        resizes.observe(host);
+        const themes = new MutationObserver(() => restyle(latest.current.fontSize, latest.current.lineHeight));
+        themes.observe(document.documentElement, { attributes: true, attributeFilter: ROOT_ATTRIBUTES });
+        return () => {
+            if (timer !== null) {
+                window.clearTimeout(timer);
+            }
+            resizes.disconnect();
+            themes.disconnect();
+            data.dispose();
+            // The context goes back before the terminal is gone, so the next one can take it.
+            current.setWebgl(false);
+            term.dispose();
+            live.current = null;
+        };
+    }, []);
+    useEffect(() => {
+        live.current?.restyle(fontSize, lineHeight);
+    }, [fontSize, lineHeight]);
+    useEffect(() => {
+        live.current?.setInput(readOnly, convertEol);
+    }, [readOnly, convertEol]);
+    useEffect(() => {
+        live.current?.setWebgl(webgl);
+    }, [webgl]);
+    return (_jsx("div", { className: clsx('terminal-view', className), role: label === undefined ? undefined : 'region', "aria-label": label, children: _jsx("div", { ref: hostRef, className: "terminal-view-host" }) }));
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { TerminalView, type TerminalSize, type TerminalViewHandle, type TerminalViewProps } from './TerminalView.tsx';
+export { webglTerminals } from './webgl-budget.ts';

package/dist/index.js

@@ -0,0 +1,2 @@
+export { TerminalView } from './TerminalView.js';
+export { webglTerminals } from './webgl-budget.js';

package/dist/terminal.css

@@ -0,0 +1,58 @@
+/* The tokens and rules of @adecore/terminal. An app imports this after the theme of @adecore/ui, whose
+   `--accent`, `--selection` and `--font-mono` the terminal reads too. */
+
+/* What `TerminalView` draws with, read as literal colors on every theme change. The cursor follows the
+   accent; the sixteen colors are the ones a program asks for by number. The selectors are the ones
+   the theme of @adecore/ui uses, so an app overrides both in one rule. */
+:root, [data-theme="light"] {
+    --term-bg: #fbfbfc;
+    --term-fg: #27272a;
+    --term-cursor: var(--accent);
+    --term-ansi-black: #3f3f46;
+    --term-ansi-red: #b91c1c;
+    --term-ansi-green: #15803d;
+    --term-ansi-yellow: #a16207;
+    --term-ansi-blue: #1d4ed8;
+    --term-ansi-magenta: #a21caf;
+    --term-ansi-cyan: #0e7490;
+    --term-ansi-white: #a1a1aa;
+    --term-ansi-bright-black: #71717a;
+    --term-ansi-bright-red: #dc2626;
+    --term-ansi-bright-green: #16a34a;
+    --term-ansi-bright-yellow: #ca8a04;
+    --term-ansi-bright-blue: #2563eb;
+    --term-ansi-bright-magenta: #c026d3;
+    --term-ansi-bright-cyan: #0891b2;
+    --term-ansi-bright-white: #e4e4e7;
+}
+
+[data-theme="dark"] {
+    --term-bg: #08080a;
+    --term-fg: #d6d6de;
+    --term-ansi-black: #2a2a31;
+    --term-ansi-red: #f87171;
+    --term-ansi-green: #4ade80;
+    --term-ansi-yellow: #fbbf24;
+    --term-ansi-blue: #60a5fa;
+    --term-ansi-magenta: #c084fc;
+    --term-ansi-cyan: #67e8f9;
+    --term-ansi-white: #d6d6de;
+    --term-ansi-bright-black: #6b6b76;
+    --term-ansi-bright-red: #fca5a5;
+    --term-ansi-bright-green: #86efac;
+    --term-ansi-bright-yellow: #fde68a;
+    --term-ansi-bright-blue: #93c5fd;
+    --term-ansi-bright-magenta: #d8b4fe;
+    --term-ansi-bright-cyan: #a5f3fc;
+    --term-ansi-bright-white: #f4f4f5;
+}
+
+/* In the components layer, so a caller's utilities, such as `absolute inset-0`, outrank the box. */
+@layer components {
+    /* The host takes no vertical padding, since the fit would count it as room for a
+       row that is cut off; the rows sit centered by the offset the fit sets instead. */
+    .terminal-view { position: relative; overflow: hidden; background: var(--term-bg); }
+    .terminal-view-host { position: absolute; inset: 0; overflow: hidden; padding: 0 0 0 8px; }
+    .terminal-view-host .xterm { height: 100%; top: var(--term-offset, 6px); }
+    .terminal-view-host .xterm .xterm-viewport { background-color: transparent !important; }
+}

package/dist/theme.d.ts

@@ -0,0 +1,3 @@
+import type { ITheme } from '@xterm/xterm';
+export declare const readTerminalTheme: () => ITheme;
+export declare const readTerminalFont: () => string;

package/dist/theme.js

@@ -0,0 +1,20 @@
+const ANSI = ['black', 'red', 'green', 'yellow', 'blue', 'magenta', 'cyan', 'white'];
+const token = (style, name) => style.getPropertyValue(name).trim();
+const brightKey = (name) => `bright${name[0].toUpperCase()}${name.slice(1)}`;
+/* xterm takes literal colors, so the tokens are resolved from the root on every theme change. */
+export const readTerminalTheme = () => {
+    const style = getComputedStyle(document.documentElement);
+    const theme = {
+        background: token(style, '--term-bg'),
+        foreground: token(style, '--term-fg'),
+        cursor: token(style, '--term-cursor'),
+        cursorAccent: token(style, '--term-bg'),
+        selectionBackground: token(style, '--selection')
+    };
+    for (const name of ANSI) {
+        theme[name] = token(style, `--term-ansi-${name}`);
+        theme[brightKey(name)] = token(style, `--term-ansi-bright-${name}`);
+    }
+    return theme;
+};
+export const readTerminalFont = () => token(getComputedStyle(document.documentElement), '--font-mono');

package/dist/webgl-budget.d.ts

@@ -0,0 +1,25 @@
+import type { Terminal } from '@xterm/xterm';
+/**
+ * Keeps the number of live WebGL renderers under the cap, however many terminals a page shows.
+ * A browser drops the oldest of its own contexts without telling anyone, which left a terminal on
+ * the DOM renderer for good; here a terminal that loses its context queues up again instead.
+ * `WebglSlots` decides who holds one, this class loads and disposes the addons.
+ */
+declare class WebglBudget {
+    private readonly slots;
+    private readonly entries;
+    register(id: string, term: Terminal, refit: () => void): () => void;
+    focus(id: string): void;
+    blur(id: string): void;
+    touch(id: string): void;
+    holders(): Terminal[];
+    private apply;
+    private load;
+    private unload;
+    private handleLoss;
+    private drop;
+    private scheduleRefit;
+}
+export declare const webglBudget: WebglBudget;
+export declare const webglTerminals: () => Terminal[];
+export {};

package/dist/webgl-budget.js

@@ -0,0 +1,143 @@
+import { DEFAULT_WEBGL_CONTEXTS, WebglSlots } from './webgl-slots.js';
+let webgl2Available = null;
+/* Loaded on the first grant, and only a terminal granted a context before that waits on it. An app
+   that registers the same import with the prefetcher has it in the module cache by then. */
+let Addon = null;
+let addonLoad = null;
+/* Probed once for the page; the probe context is released so it does not count against the browser's cap. */
+const hasWebgl2 = () => {
+    if (webgl2Available === null) {
+        const context = document.createElement('canvas').getContext('webgl2');
+        webgl2Available = context !== null;
+        context?.getExtension('WEBGL_lose_context')?.loseContext();
+    }
+    return webgl2Available;
+};
+/* The canvas the addon just added. xterm names the canvas of every render layer it owns
+   (`xterm-link-layer`); the WebGL one is the nameless one. */
+const rendererCanvas = (term) => {
+    const canvases = term.element?.querySelectorAll('.xterm-screen canvas') ?? [];
+    return [...canvases].filter((canvas) => canvas.classList.length === 0).at(-1) ?? null;
+};
+/**
+ * Keeps the number of live WebGL renderers under the cap, however many terminals a page shows.
+ * A browser drops the oldest of its own contexts without telling anyone, which left a terminal on
+ * the DOM renderer for good; here a terminal that loses its context queues up again instead.
+ * `WebglSlots` decides who holds one, this class loads and disposes the addons.
+ */
+class WebglBudget {
+    slots = new WebglSlots(DEFAULT_WEBGL_CONTEXTS);
+    entries = new Map();
+    /* A terminal that mounted visibly asks for a context. The returned function gives it back. */
+    register(id, term, refit) {
+        const entry = { term, refit, addon: null, canvas: null, frame: null };
+        this.entries.set(id, entry);
+        if (hasWebgl2()) {
+            this.apply(this.slots.request(id));
+        }
+        return () => {
+            if (this.entries.get(id) !== entry) {
+                return;
+            }
+            this.entries.delete(id);
+            // The context goes back before the next terminal asks for one, never after.
+            this.drop(entry);
+            this.apply(this.slots.release(id));
+        };
+    }
+    focus(id) {
+        this.apply(this.slots.focus(id));
+    }
+    blur(id) {
+        this.apply(this.slots.blur(id));
+    }
+    /* Output arrived; a busy terminal outranks an idle one. */
+    touch(id) {
+        this.apply(this.slots.touch(id));
+    }
+    /* The terminals holding a WebGL renderer, highest ranked first. */
+    holders() {
+        return this.slots.holders().flatMap((id) => {
+            const entry = this.entries.get(id);
+            return entry ? [entry.term] : [];
+        });
+    }
+    apply(change) {
+        // Free first, the browser has to be back under its own limit before the next context exists.
+        for (const id of change.revoked) {
+            this.unload(id);
+        }
+        for (const id of change.granted) {
+            this.load(id);
+        }
+    }
+    load(id) {
+        const entry = this.entries.get(id);
+        if (!entry || entry.addon) {
+            return;
+        }
+        if (Addon === null) {
+            addonLoad ??= import('@xterm/addon-webgl').then((module) => {
+                Addon = module.WebglAddon;
+            });
+            void addonLoad.then(() => {
+                if (this.slots.holders().includes(id)) {
+                    this.load(id);
+                }
+            }, () => this.apply(this.slots.lost(id)));
+            return;
+        }
+        try {
+            const addon = new Addon();
+            addon.onContextLoss(() => this.handleLoss(id));
+            entry.term.loadAddon(addon);
+            entry.addon = addon;
+            entry.canvas = rendererCanvas(entry.term);
+            this.scheduleRefit(entry);
+        }
+        catch {
+            // WebGL refused this terminal; the DOM renderer keeps drawing and the slot goes to the next one.
+            this.apply(this.slots.lost(id));
+        }
+    }
+    unload(id) {
+        const entry = this.entries.get(id);
+        if (!entry?.addon) {
+            return;
+        }
+        this.drop(entry);
+        // Disposing the addon puts the DOM renderer back and queues a full repaint; the fit runs
+        // after that frame, on the cell size that renderer measured.
+        this.scheduleRefit(entry);
+    }
+    handleLoss(id) {
+        this.unload(id);
+        // Not gone for good, the terminal waits in line and takes a context again when it is focused.
+        this.apply(this.slots.lost(id));
+    }
+    drop(entry) {
+        if (entry.frame !== null) {
+            window.cancelAnimationFrame(entry.frame);
+            entry.frame = null;
+        }
+        entry.addon?.dispose();
+        entry.addon = null;
+        // The addon leaves its canvas to the garbage collector, and until that runs the browser
+        // still counts the context. Losing it by hand is what makes a released slot a free one.
+        entry.canvas?.getContext('webgl2')?.getExtension('WEBGL_lose_context')?.loseContext();
+        entry.canvas = null;
+    }
+    scheduleRefit(entry) {
+        if (entry.frame !== null) {
+            return;
+        }
+        entry.frame = window.requestAnimationFrame(() => {
+            entry.frame = null;
+            entry.refit();
+        });
+    }
+}
+/* One budget for the page, since the browser's cap is per page. */
+export const webglBudget = /* @__PURE__ */ new WebglBudget();
+/* The terminals drawing with WebGL right now, highest ranked first: the focused one, then the ones written to last. */
+export const webglTerminals = () => webglBudget.holders();

package/dist/webgl-slots.d.ts

@@ -0,0 +1,30 @@
+export declare const DEFAULT_WEBGL_CONTEXTS = 10;
+export interface SlotChange {
+    granted: string[];
+    revoked: string[];
+}
+/**
+ * Hands a fixed number of WebGL contexts to the terminals that deserve them most, the focused one
+ * first, then the ones most recently focused or written to. Knows nothing about xterm or the DOM;
+ * the budget turns a `SlotChange` into addons that are loaded and disposed.
+ */
+export declare class WebglSlots {
+    private readonly members;
+    private cap;
+    private focusedId;
+    private stamp;
+    constructor(cap?: number);
+    holders(): string[];
+    holds(id: string): boolean;
+    waiting(): string[];
+    request(id: string): SlotChange;
+    release(id: string): SlotChange;
+    focus(id: string): SlotChange;
+    blur(id: string): SlotChange;
+    touch(id: string): SlotChange;
+    lost(id: string): SlotChange;
+    setCap(cap: number): SlotChange;
+    private ranked;
+    private rankOf;
+    private reconcile;
+}