@svelterm/core 0.1.0 → 0.23.0

package/docs/getting-started.md

@@ -0,0 +1,177 @@
+# Getting started
+
+svelterm runs Svelte components in a terminal. You write ordinary Svelte —
+markup, scoped `<style>`, runes, event handlers — and the renderer lays it
+out on a character-cell grid instead of a browser DOM.
+
+## Prerequisites
+
+svelterm builds on Svelte's experimental custom renderer API
+([sveltejs/svelte#18042](https://github.com/sveltejs/svelte/pull/18042)).
+Until [#18505](https://github.com/sveltejs/svelte/pull/18505) lands, use
+the svelterm fork of that branch (upstream plus the `svelte/renderer`
+mount export svelterm needs on Node):
+
+```bash
+git clone -b svelte-custom-renderer https://github.com/tomyan/svelte.git svelte-fork
+cd svelte-fork
+pnpm install
+pnpm -C packages/svelte build
+```
+
+## Scaffold a project
+
+```bash
+npx @svelterm/core init my-app        # or: svelterm init my-app
+cd my-app
+npm install
+```
+
+The scaffold expects the Svelte fork as a sibling directory
+(`../svelte-fork`) — adjust the `svelte` path in `package.json` if yours
+lives elsewhere. It contains a counter component, a vite config, and
+three scripts:
+
+```bash
+npm run dev    # vite dev server (terminal 1)
+npm run app    # the app itself, hot-reloading (terminal 2)
+npm run build  # one self-contained dist/app.mjs
+```
+
+## Dev mode
+
+`svelterm dev <url>` connects to the vite dev server over WebSocket and
+renders the app in *its own* terminal — the server terminal keeps logs
+and errors readable:
+
+- Edits to any imported module restart the app in place.
+- `console.log` from the app appears in the **vite terminal**, prefixed
+  `[svelterm]` — the app's terminal is its screen.
+- `Ctrl+C` in the app terminal exits and restores the screen.
+
+Terminal-only projects need no `vite-plugin-svelte`: svelterm's
+`terminalServer()` plugin compiles `.svelte` files for the terminal
+environment itself.
+
+## Shipping
+
+`svelterm build [entry.svelte]` bundles the component graph, the Svelte
+runtime, and svelterm into one `.mjs` (default `dist/app.mjs`) that runs
+with plain `node` — no `node_modules` at the destination:
+
+```bash
+npx svelterm build src/App.svelte -o dist/app.mjs
+node dist/app.mjs
+```
+
+Global CSS is picked up from `src/main.css`/`main.css` (or the
+`--css` flag); each component's scoped styles travel inside the bundle.
+Component libraries installed as symlinks (e.g. a local `@svelterm/ui`
+via `file:`) resolve `@svelterm/core` and `svelte` from your project, so
+they bundle correctly. See
+[distribution](./distribution.md) for platform packaging and the
+curl-pipe pattern.
+
+## Manual setup
+
+An existing project needs the compiler pointed at svelterm's renderer
+with CSS kept external. With the environment-aware `vite-plugin-svelte`
+fork (needed for dual-target; terminal-only projects can rely on
+`terminalServer()` instead):
+
+```typescript
+// vite.config.ts
+import { defineConfig } from 'vite'
+import { svelterm } from '@svelterm/core/vite'
+
+export default defineConfig({
+    plugins: [
+        ...svelterm.terminalServer({ entry: './src/App.svelte' }),
+    ],
+    environments: svelterm.environments(),
+    optimizeDeps: { exclude: ['svelte'] },
+    ssr: { noExternal: ['svelte'] },
+})
+```
+
+## A first component
+
+```svelte
+<script>
+    let count = $state(0)
+</script>
+
+<div class="counter">
+    <button onclick={() => count++}>count is {count}</button>
+</div>
+
+<style>
+    .counter {
+        padding: 1cell 2cell;
+    }
+    button {
+        border: single;
+        border-color: cyan;
+        padding: 0 1cell;
+    }
+    button:focus {
+        border-color: yellow;
+    }
+</style>
+```
+
+Run it programmatically (the CLI does this for you):
+
+```typescript
+import { run } from '@svelterm/core/app'
+import App from './App.svelte'
+import css from './App.css?raw' // the extracted stylesheet
+
+const handle = run(App, { css })
+// handle.cleanup() restores the terminal
+```
+
+Press `Tab` to focus the button, `Enter` to click it, `Ctrl+C` to exit.
+
+## `run(component, options?)`
+
+| Option | Default | Meaning |
+|---|---|---|
+| `css` | registered CSS | Extracted CSS; defaults to styles components registered via `registerComponentCss` (bundles do this automatically) |
+| `fullscreen` | `true` | Use the alternate screen buffer |
+| `mouse` | `true` | Enable mouse click/scroll/hover |
+| `props` | — | Props passed to the component |
+| `colorScheme` | auto | Force `'dark'`/`'light'` instead of OSC 11 detection |
+| `io` | process stdio | A custom `TerminalIO` (embedding, tests) |
+| `onConsole` | — | Receive `console.*` output; without it, `console.log` throws rather than corrupt the screen |
+| `mode` | `'fullscreen'` | `'inline'` renders at the shell cursor — see [inline mode](./inline-mode.md) |
+| `exitOn` | `['ctrl+c']` | Add `'ctrl+d'` for EOF-style exit |
+| `colorDepth` | detected | Force `'truecolor' \| '256' \| '16' \| 'mono'` |
+| `debug` / `debugPort` | off | WebSocket debug server |
+
+Returns `{ cleanup, setColorScheme }`. `cleanup()` unmounts, restores the
+screen and input modes; `setColorScheme('light')` re-resolves
+`light-dark()` and scheme media queries on a live app.
+
+## Writing dual-target components
+
+The same source can render in the browser. Standard CSS behaves
+identically; anything mode-specific goes in a
+[`display-mode`](./terminal-css.md) block:
+
+```css
+.card {
+    display: flex;
+    gap: 1ch;                                   /* 1ch = 1 cell, valid both sides */
+    @media (display-mode: terminal) { border: single; }
+    @media (display-mode: browser)  { border: 1px solid #ccc; border-radius: 6px; }
+}
+```
+
+Dual-target builds compile per environment, which needs the
+environment-aware [`vite-plugin-svelte` fork](https://github.com/sveltejs/vite-plugin-svelte/pull/1318)
+and the `svelterm.svelteOptions()` helper.
+
+Event payloads differ slightly: terminal events carry data on
+`event.data`, browsers on the event itself — handlers that run in both
+read `event.data?.value ?? event.target.value`.

package/docs/guide/css.md

@@ -0,0 +1,187 @@
+# CSS
+
+Svelterm uses real CSS — the same scoped `<style>` blocks that Svelte compiles for the browser. The CSS engine parses selectors, computes specificity, cascades rules, resolves variables, and evaluates media queries. The difference is how property values are interpreted: `border: rounded` draws box-drawing characters, `1cell` maps to terminal cells, colors map to ANSI codes or truecolor sequences.
+
+## Terminal-specific values
+
+These values work in the terminal and are ignored by browsers:
+
+### Border styles
+
+```css
+.box {
+    border: single;   /* ┌──┐ │  │ └──┘ */
+    border: double;   /* ╔══╗ ║  ║ ╚══╝ */
+    border: rounded;  /* ╭──╮ │  │ ╰──╯ */
+    border: heavy;    /* ┏━━┓ ┃  ┃ ┗━━┛ */
+}
+```
+
+Browsers don't recognise these values and fall back to `border: none`.
+
+### The `cell` unit
+
+Terminal cells are the fundamental unit — one character position. Use `cell` anywhere you'd use `px` or `rem`:
+
+```css
+.panel {
+    width: 30cell;
+    padding: 1cell 2cell;
+    gap: 1cell;
+}
+```
+
+Browsers ignore `cell` values since it's not a recognised CSS unit. Use `@media` blocks for browser-specific sizing:
+
+```css
+.panel { padding: 1cell; }
+
+@media (display-mode: screen) {
+    .panel { padding: 0.5rem; }
+}
+```
+
+### Opacity
+
+`opacity: dim` renders text with the terminal dim attribute (SGR code 2). Values less than 1 also trigger dim:
+
+```css
+.muted { opacity: dim; }
+.faint { opacity: 0.5; }  /* also dim */
+```
+
+## Selectors
+
+Full CSS selector support:
+
+| Selector | Example | Description |
+|---|---|---|
+| Tag | `div` | Element type |
+| Class | `.active` | Class attribute |
+| ID | `#main` | ID attribute |
+| Universal | `*` | Any element |
+| Attribute | `[href]`, `[data-type="x"]` | Attribute presence/value |
+| Descendant | `.app span` | Any descendant |
+| Child | `.app > div` | Direct child |
+| Adjacent sibling | `h1 + p` | Immediately after |
+| General sibling | `h1 ~ p` | Any sibling after |
+| `:first-child` | `li:first-child` | First child of parent |
+| `:last-child` | `li:last-child` | Last child of parent |
+| `:not()` | `div:not(.hidden)` | Negation |
+| `:focus` | `button:focus` | Has keyboard focus |
+| `:hover` | `.item:hover` | Mouse is over element |
+| `:root` | `:root` | Root element |
+
+Svelte's scoped class hashes (e.g. `.svelte-abc123`) work naturally — they're just class selectors.
+
+## Colors
+
+### ANSI named colors
+
+```css
+.error { color: red; }
+.info { color: cyan; }
+.warning { color: yellow; background-color: black; }
+```
+
+The 8 base ANSI colors: `black`, `red`, `green`, `yellow`, `blue`, `magenta`, `cyan`, `white`.
+
+### Truecolor (24-bit)
+
+```css
+.brand { color: #ff6b6b; }
+.accent { color: rgb(81, 207, 102); }
+.highlight { color: hsl(210, 100%, 60%); }
+```
+
+Hex (3 and 6 digit), `rgb()`, `rgba()`, `hsl()`, `hsla()` all produce 24-bit truecolor output.
+
+### CSS named colors
+
+All 148 CSS Level 4 named colors are supported: `coral`, `teal`, `rebeccapurple`, `goldenrod`, etc.
+
+## CSS Variables
+
+```css
+:root {
+    --primary: cyan;
+    --accent: yellow;
+    --muted: gray;
+}
+
+.title { color: var(--primary); }
+.value { color: var(--accent); }
+.hint { color: var(--muted, gray); }  /* with fallback */
+```
+
+Variables cascade through the tree. Changing a class on an ancestor updates all descendants that reference its variables.
+
+## Media queries
+
+```css
+/* Terminal-only rules */
+@media (display-mode: terminal) {
+    .panel { border: rounded; padding: 1cell; }
+}
+
+/* Browser-only rules */
+@media (display-mode: screen) {
+    .panel { border-radius: 8px; padding: 0.5rem; }
+}
+
+/* Light/dark adaptation — detected automatically via OSC 11 */
+@media (prefers-color-scheme: dark) {
+    :root { --bg: black; --fg: white; }
+}
+@media (prefers-color-scheme: light) {
+    :root { --bg: #eeeeee; --fg: #111111; }
+}
+
+/* Responsive to terminal size */
+@media (min-width: 80) {
+    .sidebar { display: flex; }
+}
+```
+
+## Container queries
+
+```css
+@container (min-width: 40) {
+    .card { flex-direction: row; }
+}
+```
+
+Container queries evaluate after the first layout pass, then re-resolve styles for matching containers.
+
+## Math functions
+
+```css
+.panel {
+    width: calc(100% - 4cell);
+    height: min(20cell, 50%);
+    padding: clamp(1cell, 5%, 3cell);
+}
+```
+
+`calc()`, `min()`, `max()`, `clamp()` work in sizing properties.
+
+## Specificity and cascade
+
+Standard CSS specificity rules apply:
+
+1. ID selectors (`#main`) — highest
+2. Class, attribute, pseudo-class (`.active`, `[href]`, `:focus`) — medium
+3. Tag selectors (`div`, `span`) — lowest
+
+At equal specificity, later rules win. `inherit`, `initial`, and `unset` keywords are supported.
+
+## What's not supported
+
+Properties that don't map to terminal capabilities:
+
+- `font-family`, `font-size` — terminal is monospace, fixed size
+- `border-radius` — use `border: rounded` instead
+- `box-shadow`, `transform`, `transition` — no sub-cell rendering
+- `float` — not implemented
+- `!important` — not implemented
+- `opacity` with blending — terminal cells are opaque; opacity maps to dim

package/docs/guide/input.md

@@ -0,0 +1,143 @@
+# Input
+
+Svelterm handles keyboard, mouse, and focus input using the same event model as the browser — events dispatch to a target element, bubble up through ancestors, and can be stopped or prevented.
+
+## Keyboard events
+
+```svelte
+<div onkeydown={(e) => handleKey(e.data)}>
+    Press a key
+</div>
+```
+
+The event's `data` property contains a `KeyEvent`:
+
+```ts
+interface KeyEvent {
+    key: string       // 'a', 'Enter', 'ArrowUp', 'Tab', etc.
+    ctrl: boolean
+    shift: boolean
+    meta: boolean
+}
+```
+
+### Special keys
+
+`Enter`, `Escape`, `Backspace`, `Delete`, `Tab`, `ArrowUp`, `ArrowDown`, `ArrowLeft`, `ArrowRight`, `Home`, `End`, `PageUp`, `PageDown`, `Insert`
+
+### Built-in key handling
+
+| Key | Action |
+|---|---|
+| `Ctrl+C` | Exit the application |
+| `Ctrl+Z` | Suspend (SIGTSTP) |
+| `Tab` | Focus next focusable element |
+| `Shift+Tab` | Focus previous element |
+| `Enter` | Click the focused element |
+
+These fire before your component's `onkeydown`. All other keys are dispatched to the focused element, or to the component root if nothing is focused.
+
+## Mouse events
+
+Mouse input is enabled by default. Click, scroll, and hover events are supported.
+
+```svelte
+<button onclick={(e) => console.log('clicked at', e.data.col, e.data.row)}>
+    Click me
+</button>
+```
+
+Mouse events include position data:
+
+```ts
+interface MouseEvent {
+    button: 'left' | 'right' | 'middle' | 'scrollUp' | 'scrollDown'
+    type: 'press' | 'release' | 'motion' | 'scroll'
+    col: number
+    row: number
+}
+```
+
+### Click
+
+Clicking a focusable element (`<button>`, `<input>`, `<a>`) focuses it and dispatches a `click` event. Clicking an `<a>` element opens its `href` in the default browser.
+
+### Scroll
+
+Mouse wheel events scroll `overflow: auto/scroll` containers. The nearest scrollable ancestor of the element under the cursor receives the scroll.
+
+### Hover
+
+Mouse motion sets the `:hover` pseudo-class on the element under the cursor:
+
+```css
+.item:hover {
+    color: cyan;
+    font-weight: bold;
+}
+```
+
+## Focus management
+
+Focusable elements: `<button>`, `<input>`, `<textarea>`, `<a>`, `<select>`
+
+```css
+button:focus {
+    border-color: yellow;
+    color: yellow;
+}
+```
+
+Focus events fire when focus changes:
+
+```svelte
+<button
+    onfocus={() => console.log('gained focus')}
+    onblur={() => console.log('lost focus')}
+>
+    Tab to me
+</button>
+```
+
+When Tab moves focus to an element outside the visible scroll region, the container scrolls to reveal it.
+
+## Event dispatch
+
+Events follow the W3C model with capture and bubble phases:
+
+1. **Capture**: root → target (listeners registered on `type__capture`)
+2. **Target**: fire listeners on the target
+3. **Bubble**: target → root (normal listeners)
+
+```svelte
+<div onclick={(e) => {
+    e.stopPropagation()    // prevent bubbling
+    e.preventDefault()     // prevent default action (e.g. link navigation)
+}}>
+    Handled here
+</div>
+```
+
+## Text input
+
+`<input>` elements accept keyboard input automatically when focused:
+
+```svelte
+<input value="" oninput={(e) => value = e.data.value} />
+```
+
+Features:
+- Character insertion at cursor position
+- Backspace, Delete
+- Arrow keys move cursor
+- Home / End
+- Ctrl+A (home), Ctrl+E (end), Ctrl+U (clear to start), Ctrl+K (clear to end)
+- Horizontal scroll with overflow indicators (`…`) when text exceeds width
+- Cursor rendered as inverted cell
+- Bracketed paste support (paste from clipboard inserts as a single operation)
+
+## Disabling mouse
+
+```ts
+mount(App, { css, mouse: false })
+```

package/docs/guide/layout.md

@@ -0,0 +1,171 @@
+# Layout
+
+Svelterm implements CSS layout on a cell grid. Integer coordinates — every element occupies whole terminal cells. The layout engine supports flexbox, grid, block flow, table, and absolute positioning.
+
+## Block flow
+
+The default. Block elements stack vertically, filling available width. Inline elements flow horizontally within a line.
+
+```svelte
+<div>
+    <div>First block</div>
+    <div>Second block</div>
+    <span>inline </span><span>text flows</span>
+</div>
+```
+
+Block elements (`<div>`, `<p>`, `<h1>`, etc.) fill their parent's width by default. Inline elements (`<span>`, `<a>`, `<strong>`, etc.) shrink-wrap to content.
+
+## Flexbox
+
+```css
+.row { display: flex; flex-direction: row; gap: 2cell; }
+.col { display: flex; flex-direction: column; }
+```
+
+### Properties
+
+| Property | Values | Default |
+|---|---|---|
+| `flex-direction` | `row`, `column`, `row-reverse`, `column-reverse` | `row` |
+| `justify-content` | `start`, `end`, `center`, `space-between`, `space-around`, `space-evenly` | `start` |
+| `align-items` | `start`, `end`, `center`, `stretch` | `start` |
+| `align-self` | `auto`, `start`, `end`, `center`, `stretch` | `auto` |
+| `flex-grow` | number | `0` |
+| `flex-shrink` | number | `1` |
+| `flex-basis` | `auto`, size value | `auto` |
+| `flex-wrap` | `nowrap`, `wrap` | `nowrap` |
+| `gap` | size value | `0` |
+| `order` | number | `0` |
+| `flex` | shorthand: `<grow> [<shrink> [<basis>]]` | — |
+
+### Example: sidebar layout
+
+```svelte
+<style>
+    .app {
+        display: flex;
+        flex-direction: row;
+        height: 100%;
+    }
+    .sidebar {
+        width: 20cell;
+        border: single;
+        border-color: gray;
+    }
+    .main {
+        flex-grow: 1;
+    }
+</style>
+
+<div class="app">
+    <div class="sidebar">Navigation</div>
+    <div class="main">Content</div>
+</div>
+```
+
+## Grid
+
+```css
+.grid {
+    display: grid;
+    grid-template-columns: 1fr 2fr;
+    gap: 1cell;
+}
+```
+
+Grid supports `cell`, `%`, and `fr` (fractional) units for column and row templates. Children auto-flow into cells, wrapping to the next row when columns are filled.
+
+## Table
+
+```svelte
+<table>
+    <tr>
+        <td>Name</td>
+        <td>Status</td>
+    </tr>
+    <tr>
+        <td>Server 1</td>
+        <td>Online</td>
+    </tr>
+</table>
+```
+
+Column widths are determined by the widest cell across all rows. Cells fill their column width.
+
+## Sizing
+
+| Property | Values |
+|---|---|
+| `width`, `height` | `Ncell`, `N%`, `auto`, `calc()` |
+| `min-width`, `min-height` | `Ncell` |
+| `max-width`, `max-height` | `Ncell` |
+
+Percentage widths resolve against the parent's width. Percentage heights resolve against the parent's height (parent must have an explicit height).
+
+## Spacing
+
+```css
+.box {
+    padding: 1cell 2cell;           /* top/bottom, left/right */
+    margin: 1cell;                  /* all sides */
+    margin: 1cell 2cell 1cell 2cell; /* top, right, bottom, left */
+    margin: 0 auto;                 /* auto horizontal centering */
+}
+```
+
+Vertical margins collapse between adjacent block siblings (the larger margin wins).
+
+## Positioning
+
+```css
+.overlay {
+    position: absolute;
+    top: 2cell;
+    left: 5cell;
+}
+```
+
+`position: absolute` and `position: fixed` remove the element from flow and position it relative to its parent.
+
+## Overflow and scrolling
+
+```css
+.scrollable {
+    overflow: auto;
+    height: 20cell;
+}
+```
+
+| Value | Behaviour |
+|---|---|
+| `visible` | Content overflows (default) |
+| `hidden` | Content clipped |
+| `scroll` | Content clipped, scrollbar shown |
+| `auto` | Content clipped, scrollbar when needed |
+
+Mouse wheel scrolls `overflow: auto/scroll` containers. Tab navigation scrolls focused elements into view.
+
+## display: contents
+
+```css
+.wrapper { display: contents; }
+```
+
+The element is invisible to layout — its children are promoted to the parent's layout context. Useful for Svelte wrapper components that shouldn't add a layout box.
+
+## display: none
+
+```css
+.hidden { display: none; }
+```
+
+Element and all descendants are invisible and take no space.
+
+## Element defaults
+
+Block elements: `<div>`, `<p>`, `<h1>`–`<h6>`, `<ul>`, `<ol>`, `<li>`, `<pre>`, `<blockquote>`, `<hr>`, `<table>`
+
+Inline elements: `<span>`, `<a>`, `<strong>`, `<em>`, `<b>`, `<i>`, `<u>`, `<code>`, `<small>`
+
+`<input>` and `<textarea>` have an intrinsic minimum height of 1 row.