@svelterm/core 0.1.0

package/LICENSE

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

@@ -0,0 +1,174 @@
+# svelterm
+
+Svelte 5 components rendered to the terminal with real CSS.
+
+Write standard Svelte components with `<style>` blocks. They render in the terminal with ANSI escape sequences — flexbox layout, scoped styles, CSS variables, pseudo-classes, all on a cell grid.
+
+> **Early release.** Svelterm requires an unmerged Svelte branch (`svelte-custom-renderer` by [@paoloricciuti](https://github.com/paoloricciuti)) that adds the custom renderer API. It is not usable with mainline Svelte yet.
+
+## Example
+
+```svelte
+<script>
+    let count = $state(0)
+</script>
+
+<style>
+    .counter {
+        display: flex;
+        flex-direction: column;
+        border: rounded;
+        border-color: cyan;
+        padding: 1cell;
+        gap: 1cell;
+    }
+
+    .value {
+        color: yellow;
+        font-weight: bold;
+    }
+
+    button:focus {
+        color: cyan;
+        font-weight: bold;
+    }
+</style>
+
+<div class="counter">
+    <span>Count: <span class="value">{count}</span></span>
+    <button onclick={() => count++}>Increment</button>
+    <button onclick={() => count--}>Decrement</button>
+</div>
+```
+
+```typescript
+import { run } from '@svelterm/core/app'
+import { readFileSync } from 'fs'
+import App from './App.svelte'
+
+const css = readFileSync('./main.css', 'utf-8')
+run(App, { css })
+```
+
+## Dual-target components
+
+The same Svelte component can render in both terminal and browser. Terminal-specific CSS values (`border: rounded`, `1cell`, `opacity: dim`) are naturally ignored by browsers — they're invalid CSS. Browser-specific rules go in `@media (display-mode: screen)`.
+
+```svelte
+<style>
+    .greeting {
+        border: rounded;
+        border-color: cyan;
+        padding: 1cell;
+    }
+
+    @media (display-mode: screen) {
+        .greeting {
+            border: 2px solid #00b4d8;
+            border-radius: 8px;
+            padding: 1rem;
+        }
+    }
+</style>
+```
+
+To build for each target, use separate Vite configs — one with `customRenderer: '@svelterm/core'` for terminal, one without for browser. The component source is the same.
+
+## What's different in terminal CSS
+
+Standard CSS works as expected. These are the terminal-specific additions:
+
+| Feature | Terminal | Browser |
+|---------|----------|---------|
+| **Borders** | `single`, `double`, `rounded`, `heavy` (box-drawing characters) | Ignored (invalid values) |
+| **Units** | `cell` — one monospace character position | Ignored (unknown unit) |
+| **Opacity** | `dim` — terminal dim attribute | Ignored (invalid value) |
+| **Colors** | ANSI names, 256-color, truecolor hex, CSS named colors | Standard CSS colors |
+| **Media** | `@media (display-mode: terminal)` | `@media (display-mode: screen)` |
+
+## Features
+
+- **CSS engine** — selectors, specificity, cascade, inheritance, scoped styles, `var()`, `calc()`, `@media`, `@keyframes`
+- **Flexbox layout** — `flex-direction`, `justify-content`, `align-items`, `flex-grow`, `flex-shrink`, `gap`, `flex-wrap`
+- **Terminal rendering** — ANSI colors (16, 256, truecolor), borders, text styles, differential output
+- **Input** — keyboard events, mouse click and scroll, focus management with Tab/Shift+Tab, `:focus` and `:hover` pseudo-classes
+- **Text input** — `<input>` and `<textarea>` with readline-like editing
+- **Incremental updates** — mutation tracking classifies changes as paint-only, style-resolve, or layout to avoid full recomputation
+- **Color scheme** — automatic `prefers-color-scheme` detection via terminal queries
+
+## Prerequisites
+
+Svelterm requires the experimental custom renderer API, available on the [`svelte-custom-renderer`](https://github.com/paoloricciuti/svelte/tree/svelte-custom-renderer) branch:
+
+```bash
+# Clone the branch
+git clone -b svelte-custom-renderer https://github.com/paoloricciuti/svelte.git svelte-fork
+cd svelte-fork
+pnpm install
+pnpm -C packages/svelte build
+```
+
+Then reference it in your project's `package.json`:
+
+```json
+{
+    "peerDependencies": {
+        "svelte": "file:../svelte-fork/packages/svelte"
+    }
+}
+```
+
+## Setup
+
+Configure the Svelte compiler to use svelterm as the custom renderer:
+
+```typescript
+// vite.config.ts
+import { defineConfig } from 'vite'
+import { svelte } from '@sveltejs/vite-plugin-svelte'
+
+export default defineConfig({
+    plugins: [
+        svelte({
+            compilerOptions: {
+                experimental: {
+                    customRenderer: '@svelterm/core',
+                },
+                css: 'external',
+            },
+        }),
+    ],
+    build: {
+        target: 'node22',
+        rollupOptions: {
+            external: ['svelte', 'svelte/renderer', 'svelte/internal',
+                        'svelte/internal/client', 'ws', 'http', 'crypto'],
+        },
+    },
+})
+```
+
+## API
+
+### `run(component, options?)`
+
+Start an interactive terminal application.
+
+```typescript
+import { run } from '@svelterm/core/app'
+
+const stop = run(App, {
+    css,                    // Extracted CSS string
+    fullscreen: true,       // Use alternate screen buffer (default: true)
+    mouse: true,            // Enable mouse input (default: true)
+    props: { name: 'world' },
+})
+
+// Call stop() to shut down and restore terminal
+```
+
+Returns a function that stops the application, unmounts the component, and restores the terminal.
+
+## License
+
+MIT

package/dist/src/components/spinner.d.ts

@@ -0,0 +1,11 @@
+export declare const SPINNER_DOTS: string[];
+export declare const SPINNER_LINE: string[];
+export declare const SPINNER_BRAILLE: string[];
+export declare class Spinner {
+    private frames;
+    private index;
+    constructor(frames?: string[]);
+    get frame(): string;
+    tick(): void;
+    reset(): void;
+}

package/dist/src/components/spinner.js

@@ -0,0 +1,19 @@
+export const SPINNER_DOTS = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+export const SPINNER_LINE = ['|', '/', '-', '\\'];
+export const SPINNER_BRAILLE = ['⣾', '⣽', '⣻', '⢿', '⡿', '⣟', '⣯', '⣷'];
+export class Spinner {
+    frames;
+    index = 0;
+    constructor(frames = SPINNER_DOTS) {
+        this.frames = frames;
+    }
+    get frame() {
+        return this.frames[this.index];
+    }
+    tick() {
+        this.index = (this.index + 1) % this.frames.length;
+    }
+    reset() {
+        this.index = 0;
+    }
+}

package/dist/src/components/text-buffer.d.ts

@@ -0,0 +1,21 @@
+import type { KeyEvent } from '../input/keyboard.js';
+export declare class TextBuffer {
+    private _text;
+    private _cursor;
+    constructor(initial?: string);
+    get text(): string;
+    set text(value: string);
+    get cursor(): number;
+    set cursor(value: number);
+    insert(chars: string): void;
+    delete(): void;
+    backspace(): void;
+    moveLeft(): void;
+    moveRight(): void;
+    home(): void;
+    end(): void;
+    clearToStart(): void;
+    clearToEnd(): void;
+    handleKey(key: KeyEvent): boolean;
+    private handleCtrl;
+}

package/dist/src/components/text-buffer.js

@@ -0,0 +1,87 @@
+export class TextBuffer {
+    _text;
+    _cursor;
+    constructor(initial = '') {
+        this._text = initial;
+        this._cursor = initial.length;
+    }
+    get text() { return this._text; }
+    set text(value) { this._text = value; }
+    get cursor() { return this._cursor; }
+    set cursor(value) {
+        this._cursor = Math.max(0, Math.min(value, this._text.length));
+    }
+    insert(chars) {
+        this._text = this._text.substring(0, this._cursor) + chars + this._text.substring(this._cursor);
+        this._cursor += chars.length;
+    }
+    delete() {
+        if (this._cursor >= this._text.length)
+            return;
+        this._text = this._text.substring(0, this._cursor) + this._text.substring(this._cursor + 1);
+    }
+    backspace() {
+        if (this._cursor <= 0)
+            return;
+        this._text = this._text.substring(0, this._cursor - 1) + this._text.substring(this._cursor);
+        this._cursor--;
+    }
+    moveLeft() { this.cursor--; }
+    moveRight() { this.cursor++; }
+    home() { this._cursor = 0; }
+    end() { this._cursor = this._text.length; }
+    clearToStart() {
+        this._text = this._text.substring(this._cursor);
+        this._cursor = 0;
+    }
+    clearToEnd() {
+        this._text = this._text.substring(0, this._cursor);
+    }
+    handleKey(key) {
+        if (key.ctrl)
+            return this.handleCtrl(key.key);
+        switch (key.key) {
+            case 'Backspace':
+                this.backspace();
+                return true;
+            case 'Delete':
+                this.delete();
+                return true;
+            case 'ArrowLeft':
+                this.moveLeft();
+                return true;
+            case 'ArrowRight':
+                this.moveRight();
+                return true;
+            case 'Home':
+                this.home();
+                return true;
+            case 'End':
+                this.end();
+                return true;
+            default:
+                if (key.key.length === 1) {
+                    this.insert(key.key);
+                    return true;
+                }
+                return false;
+        }
+    }
+    handleCtrl(key) {
+        switch (key) {
+            case 'a':
+                this.home();
+                return true;
+            case 'e':
+                this.end();
+                return true;
+            case 'u':
+                this.clearToStart();
+                return true;
+            case 'k':
+                this.clearToEnd();
+                return true;
+            default: return false;
+        }
+    }
+}

package/dist/src/css/animation-runner.d.ts

@@ -0,0 +1,17 @@
+import type { KeyframeStop } from './parser.js';
+import type { ResolvedStyle } from './compute.js';
+/**
+ * Runs a CSS animation by applying keyframe properties at the current time.
+ * Terminal animations are discrete (no interpolation between color values).
+ */
+export declare class AnimationRunner {
+    private keyframes;
+    private duration;
+    private iterations;
+    constructor(keyframes: KeyframeStop[], durationMs: number, iterations: number);
+    /** Apply the appropriate keyframe declarations to a style at the given elapsed time */
+    apply(style: ResolvedStyle, elapsedMs: number): void;
+    isFinished(elapsedMs: number): boolean;
+    private getProgress;
+    private getKeyframeAt;
+}

package/dist/src/css/animation-runner.js

@@ -0,0 +1,72 @@
+import { resolveColor } from './color.js';
+/**
+ * Runs a CSS animation by applying keyframe properties at the current time.
+ * Terminal animations are discrete (no interpolation between color values).
+ */
+export class AnimationRunner {
+    keyframes;
+    duration;
+    iterations;
+    constructor(keyframes, durationMs, iterations) {
+        this.keyframes = keyframes.sort((a, b) => a.offset - b.offset);
+        this.duration = durationMs;
+        this.iterations = iterations;
+    }
+    /** Apply the appropriate keyframe declarations to a style at the given elapsed time */
+    apply(style, elapsedMs) {
+        if (this.keyframes.length === 0 || this.duration <= 0)
+            return;
+        const progress = this.getProgress(elapsedMs);
+        const kf = this.getKeyframeAt(progress);
+        if (!kf)
+            return;
+        for (const decl of kf.declarations) {
+            applyAnimatedProperty(style, decl);
+        }
+    }
+    isFinished(elapsedMs) {
+        if (this.iterations === Infinity)
+            return false;
+        return elapsedMs >= this.duration * this.iterations;
+    }
+    getProgress(elapsedMs) {
+        if (this.iterations === Infinity) {
+            return (elapsedMs % this.duration) / this.duration;
+        }
+        const totalDuration = this.duration * this.iterations;
+        if (elapsedMs >= totalDuration)
+            return 1; // finished — hold at end
+        return (elapsedMs % this.duration) / this.duration;
+    }
+    getKeyframeAt(progress) {
+        // Discrete: find the last keyframe whose offset <= progress
+        let result = null;
+        for (const kf of this.keyframes) {
+            if (kf.offset <= progress)
+                result = kf;
+            else
+                break;
+        }
+        return result ?? this.keyframes[0];
+    }
+}
+function applyAnimatedProperty(style, decl) {
+    switch (decl.property) {
+        case 'color':
+            style.fg = resolveColor(decl.value);
+            break;
+        case 'background-color':
+        case 'background':
+            style.bg = resolveColor(decl.value);
+            break;
+        case 'font-weight':
+            style.bold = decl.value === 'bold' || parseInt(decl.value) >= 700;
+            break;
+        case 'font-style':
+            style.italic = decl.value === 'italic';
+            break;
+        case 'opacity':
+            style.dim = decl.value === 'dim' || (parseFloat(decl.value) < 1);
+            break;
+    }
+}

package/dist/src/css/animation.d.ts

@@ -0,0 +1,5 @@
+import type { CSSStyleSheet, KeyframeStop } from './parser.js';
+/**
+ * Extract keyframe definitions from a parsed stylesheet.
+ */
+export declare function getKeyframes(sheet: CSSStyleSheet): Map<string, KeyframeStop[]>;

package/dist/src/css/animation.js

@@ -0,0 +1,6 @@
+/**
+ * Extract keyframe definitions from a parsed stylesheet.
+ */
+export function getKeyframes(sheet) {
+    return sheet.keyframes;
+}

package/dist/src/css/calc.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Evaluate CSS math functions: calc(), min(), max(), clamp().
+ * Returns the computed cell value, or null if the input is not a math function.
+ */
+export declare function evaluateCalc(value: string, available: number): number | null;

package/dist/src/css/calc.js

@@ -0,0 +1,130 @@
+/**
+ * Evaluate CSS math functions: calc(), min(), max(), clamp().
+ * Returns the computed cell value, or null if the input is not a math function.
+ */
+export function evaluateCalc(value, available) {
+    const trimmed = value.trim();
+    if (trimmed.startsWith('calc(')) {
+        const expr = trimmed.slice(5, -1).trim();
+        return Math.round(evaluateExpression(expr, available));
+    }
+    if (trimmed.startsWith('min(')) {
+        const args = splitArgs(trimmed.slice(4, -1));
+        const values = args.map(a => resolveValue(a.trim(), available));
+        return Math.round(Math.min(...values));
+    }
+    if (trimmed.startsWith('max(')) {
+        const args = splitArgs(trimmed.slice(4, -1));
+        const values = args.map(a => resolveValue(a.trim(), available));
+        return Math.round(Math.max(...values));
+    }
+    if (trimmed.startsWith('clamp(')) {
+        const args = splitArgs(trimmed.slice(6, -1));
+        if (args.length !== 3)
+            return null;
+        const min = resolveValue(args[0].trim(), available);
+        const preferred = resolveValue(args[1].trim(), available);
+        const max = resolveValue(args[2].trim(), available);
+        return Math.round(Math.min(Math.max(preferred, min), max));
+    }
+    return null;
+}
+function evaluateExpression(expr, available) {
+    // Tokenize: split on +, -, *, / while preserving the operators
+    const tokens = tokenize(expr);
+    if (tokens.length === 0)
+        return 0;
+    // First pass: resolve values
+    const values = [];
+    const ops = [];
+    for (const token of tokens) {
+        if (token === '+' || token === '-' || token === '*' || token === '/') {
+            ops.push(token);
+        }
+        else {
+            values.push(resolveValue(token.trim(), available));
+        }
+    }
+    // Second pass: * and / first
+    let i = 0;
+    while (i < ops.length) {
+        if (ops[i] === '*') {
+            values[i] = values[i] * values[i + 1];
+            values.splice(i + 1, 1);
+            ops.splice(i, 1);
+        }
+        else if (ops[i] === '/') {
+            values[i] = values[i] / values[i + 1];
+            values.splice(i + 1, 1);
+            ops.splice(i, 1);
+        }
+        else {
+            i++;
+        }
+    }
+    // Third pass: + and -
+    let result = values[0];
+    for (let j = 0; j < ops.length; j++) {
+        if (ops[j] === '+')
+            result += values[j + 1];
+        else if (ops[j] === '-')
+            result -= values[j + 1];
+    }
+    return result;
+}
+function tokenize(expr) {
+    const tokens = [];
+    let current = '';
+    for (let i = 0; i < expr.length; i++) {
+        const ch = expr[i];
+        if ((ch === '+' || ch === '-') && current.trim() && i > 0 && expr[i - 1] !== '(') {
+            tokens.push(current.trim());
+            tokens.push(ch);
+            current = '';
+        }
+        else if (ch === '*' || ch === '/') {
+            tokens.push(current.trim());
+            tokens.push(ch);
+            current = '';
+        }
+        else {
+            current += ch;
+        }
+    }
+    if (current.trim())
+        tokens.push(current.trim());
+    return tokens.filter(Boolean);
+}
+function resolveValue(value, available) {
+    const trimmed = value.trim();
+    if (trimmed.endsWith('%')) {
+        return available * parseFloat(trimmed) / 100;
+    }
+    if (trimmed.endsWith('cell')) {
+        return parseFloat(trimmed);
+    }
+    // Bare number (for multipliers like * 2)
+    const num = parseFloat(trimmed);
+    return isNaN(num) ? 0 : num;
+}
+function splitArgs(argsStr) {
+    const args = [];
+    let current = '';
+    let depth = 0;
+    for (const ch of argsStr) {
+        if (ch === '(')
+            depth++;
+        if (ch === ')')
+            depth--;
+        if (ch === ',' && depth === 0) {
+            args.push(current);
+            current = '';
+        }
+        else {
+            current += ch;
+        }
+    }
+    if (current.trim())
+        args.push(current);
+    return args;
+}

package/dist/src/css/color.d.ts

@@ -0,0 +1 @@
+export declare function resolveColor(value: string): string;