@svelterm/core 0.1.0

package/dist/src/css/specificity.js

@@ -0,0 +1,89 @@
+/**
+ * Compute CSS specificity as [id, class, element] tuple.
+ * Higher tuple wins. Equal specificity: later rule wins.
+ */
+export function computeSpecificity(selector) {
+    let ids = 0;
+    let classes = 0;
+    let elements = 0;
+    let pos = 0;
+    while (pos < selector.length) {
+        const ch = selector[pos];
+        if (ch === '*') {
+            pos++; // universal: 0 specificity
+        }
+        else if (ch === '#') {
+            ids++;
+            pos++;
+            pos = skipName(selector, pos);
+        }
+        else if (ch === '.') {
+            classes++;
+            pos++;
+            pos = skipName(selector, pos);
+        }
+        else if (ch === '[') {
+            classes++; // attribute selector = class-level
+            pos = skipUntil(selector, pos, ']') + 1;
+        }
+        else if (ch === ':') {
+            pos++;
+            const nameStart = pos;
+            pos = skipName(selector, pos);
+            const name = selector.substring(nameStart, pos);
+            if (name === 'not' && pos < selector.length && selector[pos] === '(') {
+                // :not() specificity = specificity of its argument
+                pos++;
+                const argStart = pos;
+                let depth = 1;
+                while (pos < selector.length && depth > 0) {
+                    if (selector[pos] === '(')
+                        depth++;
+                    else if (selector[pos] === ')')
+                        depth--;
+                    if (depth > 0)
+                        pos++;
+                }
+                const arg = selector.substring(argStart, pos);
+                pos++; // skip )
+                const argSpec = computeSpecificity(arg);
+                ids += argSpec[0];
+                classes += argSpec[1];
+                elements += argSpec[2];
+            }
+            else if (pos < selector.length && selector[pos] === '(') {
+                classes++; // other functional pseudo-class
+                pos = skipUntil(selector, pos, ')') + 1;
+            }
+            else {
+                classes++; // simple pseudo-class
+            }
+        }
+        else if (/[a-zA-Z]/.test(ch)) {
+            elements++;
+            pos = skipName(selector, pos);
+        }
+        else {
+            pos++; // whitespace, combinators
+        }
+    }
+    return [ids, classes, elements];
+}
+function skipName(selector, pos) {
+    while (pos < selector.length && /[a-zA-Z0-9_-]/.test(selector[pos]))
+        pos++;
+    return pos;
+}
+function skipUntil(selector, pos, char) {
+    while (pos < selector.length && selector[pos] !== char)
+        pos++;
+    return pos;
+}
+/** Compare two specificity tuples. Returns positive if a wins, negative if b wins, 0 if equal. */
+export function compareSpecificity(a, b) {
+    if (a[0] !== b[0])
+        return a[0] - b[0];
+    if (a[1] !== b[1])
+        return a[1] - b[1];
+    return a[2] - b[2];
+}

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

@@ -0,0 +1,17 @@
+import type { ResolvedStyle } from './compute.js';
+/**
+ * Parse a cell value from CSS. Accepts:
+ * - `5cell` → 5
+ * - `0` → 0 (unitless zero is valid CSS)
+ * - Returns 0 for unrecognised values (browser-only units like px, em, rem)
+ */
+export declare function parseCellValue(value: string): number;
+export declare function parseSizeValue(value: string): number | string | null;
+export declare function parseJustify(value: string): ResolvedStyle['justifyContent'];
+export declare function parseAlign(value: string): ResolvedStyle['alignItems'];
+export declare function parsePadding(value: string): {
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+};

package/dist/src/css/values.js

@@ -0,0 +1,58 @@
+/**
+ * Parse a cell value from CSS. Accepts:
+ * - `5cell` → 5
+ * - `0` → 0 (unitless zero is valid CSS)
+ * - Returns 0 for unrecognised values (browser-only units like px, em, rem)
+ */
+export function parseCellValue(value) {
+    if (value === '0')
+        return 0;
+    if (value.endsWith('cell')) {
+        const num = parseFloat(value);
+        return isNaN(num) ? 0 : Math.round(num);
+    }
+    return 0;
+}
+export function parseSizeValue(value) {
+    if (value === 'auto')
+        return null;
+    if (value.endsWith('%'))
+        return value;
+    // Preserve calc/min/max/clamp expressions as strings for layout-time evaluation
+    if (value.startsWith('calc(') || value.startsWith('min(') || value.startsWith('max(') || value.startsWith('clamp(')) {
+        return value;
+    }
+    return parseCellValue(value);
+}
+export function parseJustify(value) {
+    const map = {
+        'flex-start': 'start', 'start': 'start',
+        'flex-end': 'end', 'end': 'end',
+        'center': 'center',
+        'space-between': 'space-between',
+        'space-around': 'space-around',
+        'space-evenly': 'space-evenly',
+    };
+    return map[value] ?? 'start';
+}
+export function parseAlign(value) {
+    const map = {
+        'flex-start': 'start', 'start': 'start',
+        'flex-end': 'end', 'end': 'end',
+        'center': 'center', 'stretch': 'stretch',
+    };
+    return map[value] ?? 'start';
+}
+export function parsePadding(value) {
+    const parts = value.split(/\s+/).map(parseCellValue);
+    if (parts.length === 1) {
+        return { top: parts[0], right: parts[0], bottom: parts[0], left: parts[0] };
+    }
+    if (parts.length === 2) {
+        return { top: parts[0], right: parts[1], bottom: parts[0], left: parts[1] };
+    }
+    if (parts.length === 3) {
+        return { top: parts[0], right: parts[1], bottom: parts[2], left: parts[1] };
+    }
+    return { top: parts[0], right: parts[1], bottom: parts[2], left: parts[3] };
+}

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

@@ -0,0 +1,6 @@
+import { TermNode } from '../renderer/node.js';
+import { CSSStyleSheet } from './parser.js';
+/** Collect custom properties for each element, with inheritance from ancestors. */
+export declare function collectVariables(root: TermNode, stylesheet: CSSStyleSheet): Map<number, Map<string, string>>;
+/** Resolve var() references in a CSS value. */
+export declare function resolveVar(value: string, vars: Map<string, string>): string;

package/dist/src/css/variables.js

@@ -0,0 +1,42 @@
+import { matchesSelector } from './selector.js';
+/** Collect custom properties for each element, with inheritance from ancestors. */
+export function collectVariables(root, stylesheet) {
+    const result = new Map();
+    collectNode(root, stylesheet, result, new Map());
+    return result;
+}
+function collectNode(node, stylesheet, result, inherited) {
+    if (node.nodeType !== 'element')
+        return;
+    // Start with inherited variables
+    const vars = new Map(inherited);
+    // Add variables from matching rules
+    for (const rule of stylesheet.rules) {
+        if (!rule.selectors.some(sel => matchesSelector(node, sel)))
+            continue;
+        for (const decl of rule.declarations) {
+            if (decl.property.startsWith('--')) {
+                vars.set(decl.property, decl.value);
+            }
+        }
+    }
+    result.set(node.id, vars);
+    for (const child of node.children) {
+        collectNode(child, stylesheet, result, vars);
+    }
+}
+const VAR_RE = /var\(\s*(--[a-zA-Z0-9_-]+)\s*(?:,\s*([^)]+))?\)/;
+/** Resolve var() references in a CSS value. */
+export function resolveVar(value, vars) {
+    let resolved = value;
+    let match;
+    // Resolve iteratively (handles nested vars if needed)
+    let limit = 10;
+    while ((match = VAR_RE.exec(resolved)) && limit-- > 0) {
+        const varName = match[1];
+        const fallback = match[2]?.trim();
+        const replacement = vars.get(varName) ?? fallback ?? '';
+        resolved = resolved.substring(0, match.index) + replacement + resolved.substring(match.index + match[0].length);
+    }
+    return resolved;
+}

package/dist/src/debug/console.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Console domain — intercepts console.log/warn/error/info and forwards
+ * to debug clients as events. Also captures uncaught errors.
+ */
+import { DebugServer, type DebugDomain } from './server.js';
+export declare class ConsoleDomain implements DebugDomain {
+    private server;
+    private buffer;
+    private maxBuffer;
+    private originals;
+    constructor(server: DebugServer);
+    start(): void;
+    stop(): void;
+    handle(method: string, params: Record<string, any>): any;
+    private capture;
+}

package/dist/src/debug/console.js

@@ -0,0 +1,65 @@
+/**
+ * Console domain — intercepts console.log/warn/error/info and forwards
+ * to debug clients as events. Also captures uncaught errors.
+ */
+export class ConsoleDomain {
+    server;
+    buffer = [];
+    maxBuffer = 1000;
+    originals;
+    constructor(server) {
+        this.server = server;
+        // Save originals before patching
+        this.originals = {
+            log: console.log.bind(console),
+            warn: console.warn.bind(console),
+            error: console.error.bind(console),
+            info: console.info.bind(console),
+            debug: console.debug.bind(console),
+        };
+    }
+    start() {
+        const levels = ['log', 'warn', 'error', 'info', 'debug'];
+        for (const level of levels) {
+            const original = this.originals[level];
+            console[level] = (...args) => {
+                this.capture(level, args);
+            };
+        }
+        // Capture uncaught errors
+        process.on('uncaughtException', (err) => {
+            this.capture('error', [`Uncaught: ${err.stack ?? err.message}`]);
+        });
+    }
+    stop() {
+        // Restore originals
+        console.log = this.originals.log;
+        console.warn = this.originals.warn;
+        console.error = this.originals.error;
+        console.info = this.originals.info;
+        console.debug = this.originals.debug;
+    }
+    handle(method, params) {
+        switch (method) {
+            case 'getEntries':
+                return { entries: this.buffer.slice(-(params.count ?? 100)) };
+            case 'clear':
+                this.buffer = [];
+                return {};
+            default:
+                throw new Error(`Console.${method} not implemented`);
+        }
+    }
+    capture(level, args) {
+        const entry = {
+            level,
+            args: args.map(a => typeof a === 'string' ? a : JSON.stringify(a, null, 2) ?? String(a)),
+            timestamp: Date.now(),
+        };
+        this.buffer.push(entry);
+        if (this.buffer.length > this.maxBuffer) {
+            this.buffer.shift();
+        }
+        this.server.emit('Console.messageAdded', { entry });
+    }
+}

package/dist/src/debug/server.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Svelterm Debug Protocol server.
+ * WebSocket server on localhost using the ws package.
+ * Only active when explicitly opted in via mount({ debug: true }).
+ */
+export interface DebugDomain {
+    handle(method: string, params: Record<string, any>): any;
+}
+export declare class DebugServer {
+    private wss;
+    private clients;
+    private domains;
+    private port;
+    constructor(port?: number);
+    registerDomain(name: string, domain: DebugDomain): void;
+    start(): Promise<void>;
+    get actualPort(): number;
+    stop(): void;
+    emit(method: string, params: Record<string, any>): void;
+    get connected(): number;
+    private handleMessage;
+}

package/dist/src/debug/server.js

@@ -0,0 +1,90 @@
+/**
+ * Svelterm Debug Protocol server.
+ * WebSocket server on localhost using the ws package.
+ * Only active when explicitly opted in via mount({ debug: true }).
+ */
+import { WebSocketServer, WebSocket } from 'ws';
+export class DebugServer {
+    wss = null;
+    clients = new Set();
+    domains = new Map();
+    port;
+    constructor(port = 9444) {
+        this.port = port;
+    }
+    registerDomain(name, domain) {
+        this.domains.set(name, domain);
+    }
+    start() {
+        return new Promise((resolve) => {
+            this.wss = new WebSocketServer({ host: '127.0.0.1', port: this.port }, () => {
+                const addr = this.wss?.address();
+                if (addr && typeof addr !== 'string')
+                    this.port = addr.port;
+                resolve();
+            });
+            this.wss.on('connection', (ws) => {
+                this.clients.add(ws);
+                ws.on('message', (data) => {
+                    try {
+                        const msg = JSON.parse(data.toString());
+                        this.handleMessage(ws, msg);
+                    }
+                    catch {
+                        // Malformed — ignore
+                    }
+                });
+                ws.on('close', () => { this.clients.delete(ws); });
+                ws.on('error', () => { this.clients.delete(ws); });
+            });
+            this.wss.on('error', (err) => {
+                console.error(`[debug] server error: ${err.message}`);
+                resolve(); // don't block — debug is best-effort
+            });
+        });
+    }
+    get actualPort() {
+        return this.port;
+    }
+    stop() {
+        for (const client of this.clients)
+            client.close();
+        this.clients.clear();
+        this.wss?.close();
+        this.wss = null;
+    }
+    emit(method, params) {
+        if (this.clients.size === 0)
+            return;
+        const msg = JSON.stringify({ method, params });
+        for (const client of this.clients) {
+            if (client.readyState === WebSocket.OPEN) {
+                client.send(msg);
+            }
+        }
+    }
+    get connected() {
+        return this.clients.size;
+    }
+    handleMessage(ws, msg) {
+        const dotIdx = msg.method.indexOf('.');
+        if (dotIdx === -1) {
+            ws.send(JSON.stringify({ id: msg.id, error: { message: `Invalid method: ${msg.method}` } }));
+            return;
+        }
+        const domainName = msg.method.substring(0, dotIdx);
+        const methodName = msg.method.substring(dotIdx + 1);
+        const domain = this.domains.get(domainName);
+        if (!domain) {
+            ws.send(JSON.stringify({ id: msg.id, error: { message: `Unknown domain: ${domainName}` } }));
+            return;
+        }
+        try {
+            const result = domain.handle(methodName, msg.params ?? {});
+            ws.send(JSON.stringify({ id: msg.id, result: result ?? {} }));
+        }
+        catch (err) {
+            ws.send(JSON.stringify({ id: msg.id, error: { message: err.message ?? 'Unknown error' } }));
+        }
+    }
+}

package/dist/src/headless.d.ts

@@ -0,0 +1,21 @@
+import type { Component, ComponentType, SvelteComponent } from 'svelte';
+import { TermNode } from './renderer/index.js';
+import { CellBuffer } from './render/buffer.js';
+export interface RenderResult {
+    buffer: CellBuffer;
+    root: TermNode;
+    unmount: () => void;
+}
+/**
+ * Render a Svelte component headlessly (no terminal) for testing.
+ * Returns the cell buffer, virtual tree, and unmount function.
+ */
+export declare function renderHeadless<Props extends Record<string, any>>(AppComponent: ComponentType<SvelteComponent<Props>> | Component<Props>, options?: {
+    width?: number;
+    height?: number;
+    css?: string;
+    props?: Props;
+}): RenderResult;
+export { bufferToText, bufferToStyledText, bufferToSvg } from './render/snapshot.js';
+export { CellBuffer } from './render/buffer.js';
+export { TermNode } from './renderer/node.js';

package/dist/src/headless.js

@@ -0,0 +1,26 @@
+import { TermNode } from './renderer/index.js';
+import renderer from './renderer/default.js';
+import { CellBuffer } from './render/buffer.js';
+import { paint } from './render/paint.js';
+import { parseCSS } from './css/parser.js';
+import { resolveStyles } from './css/compute.js';
+import { computeLayout } from './layout/engine.js';
+/**
+ * Render a Svelte component headlessly (no terminal) for testing.
+ * Returns the cell buffer, virtual tree, and unmount function.
+ */
+export function renderHeadless(AppComponent, options = {}) {
+    const width = options.width ?? 80;
+    const height = options.height ?? 24;
+    const root = new TermNode('element', 'root');
+    const stylesheet = options.css ? parseCSS(options.css) : null;
+    const { unmount } = renderer.render(AppComponent, { target: root, props: options.props ?? {} });
+    const buffer = new CellBuffer(width, height);
+    const styles = stylesheet ? resolveStyles(root, stylesheet) : undefined;
+    const layout = styles ? computeLayout(root, styles, width, height) : undefined;
+    paint(root, buffer, styles, layout);
+    return { buffer, root, unmount };
+}
+export { bufferToText, bufferToStyledText, bufferToSvg } from './render/snapshot.js';
+export { CellBuffer } from './render/buffer.js';
+export { TermNode } from './renderer/node.js';

package/dist/src/index.d.ts

@@ -0,0 +1,18 @@
+import type { Component, ComponentType, SvelteComponent } from 'svelte';
+export interface MountOptions {
+    fullscreen?: boolean;
+    css?: string;
+    mouse?: boolean;
+    debug?: boolean;
+    debugPort?: number;
+}
+export declare function run<Props extends Record<string, any>>(AppComponent: ComponentType<SvelteComponent<Props>> | Component<Props>, options?: MountOptions & ({} extends Props ? {
+    props?: Props;
+} : {
+    props: Props;
+})): () => void;
+export { TermNode } from './renderer/node.js';
+export { CellBuffer } from './render/buffer.js';
+export { parseCSS } from './css/parser.js';
+export { resolveStyles } from './css/compute.js';
+export { StdinRouter } from './terminal/stdin-router.js';