# XWUITerminal

CLI-style terminal component. Reuses XWUIScrollArea for output.

## Basic Usage

A dark terminal preloaded with a short session of output lines under the default prompt.

```example
file: examples/BasicUsage.ts
html: examples/BasicUsage.html
title: Basic Usage
description: A dark terminal preloaded with a short session of output lines under the default prompt.
```

## Custom Prompt

Each output line is prefixed with the configured `prompt`. Set it to a shell-style string to mimic a real session.

```example
file: examples/CustomPrompt.ts
html: examples/CustomPrompt.html
title: Custom Prompt
description: A terminal with a custom shell prompt string rendering a short git command session.
```

## Light Theme

The terminal ships dark by default; pass `theme: "light"` to render it on a light surface for embedding in bright pages.

```example
file: examples/LightTheme.ts
html: examples/LightTheme.html
title: Light Theme
description: The same CLI output rendered with the light theme instead of the default dark theme.
```

## ANSI Colors & Streaming

Pass `ansi: true` to parse ANSI output into styled output; all text is HTML-escaped and non-SGR escape sequences (cursor moves, erases, OSC other than hyperlinks) are stripped. Supported SGR: reset, bold/dim/italic/underline/strikethrough/inverse (+ per-attribute resets), standard + bright foreground **and** background colors, 256-color (`38;5;n` / `48;5;n` - xterm cube + grayscale ramp) and truecolor (`38;2;r;g;b` / `48;2;r;g;b`). OSC 8 hyperlinks (`\x1b]8;;<url>\x1b\\…\x1b]8;;\x1b\\`, BEL form too) render as links, and bare `https://…` URLs are auto-linked.

WHY a fixed terminal palette rather than xwui tokens for named colors: ANSI colors are payload semantics (the CLI author meant "red"), not theme. Numeric colors (256/truecolor) are rendered exactly as specified.

Use `appendChunk(text)` to stream partial output onto the current last line - `appendLine` still commits a full line. The parser is a cross-chunk state machine: an escape sequence split across chunks is buffered until complete (never tofu), a surrogate pair is never split at a chunk edge, and SGR/link state persists across chunks.

Security: text always renders through `textContent` (never `innerHTML`); links are sanitized to `http/https` only and get `rel="noopener noreferrer"` + `target="_blank"`.

```ts
const term = new XWUITerminal(document.getElementById("app")!, {}, { ansi: true, prompt: "" });
term.appendLine("\x1b[1;32m✓ build ok\x1b[0m");
term.appendChunk("\x1b[38;5;204mdownloading…\x1b[0m ");
term.appendChunk("42%");
```

## Scrollback Window & Stick-to-bottom

`maxLines` (default 5000) bounds the scrollback: when output exceeds the window, the oldest lines are trimmed from the DOM **and** from `data.lines`, so a 10k+ line stream never degrades the page - the DOM never holds more than `maxLines` lines. This is a hard-cap window (xterm.js-style scrollback bound), not viewport virtualization: every line inside the window is a real DOM node, so find-in-page and selection work normally.

Auto-scroll follows output only while the user is at the bottom (within 4 px); scrolling up during a stream stops following until they scroll back down.

Rendering is incremental: appends parse only the new tail and append the affected nodes - the existing buffer is never re-parsed or re-rendered per chunk. Styled spans share a per-document stylesheet with deduped generated classes instead of per-element inline styles.

```api
```