@svelterm/core 0.1.0 → 0.21.0

package/dist/src/cli/bundle.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Pure helpers behind `svelterm build` — the parts that don't need
+ * rolldown: code generation for the bundle and project-layout discovery.
+ */
+export declare const GLOBAL_CSS_MODULE = "\0svelterm:global-css";
+export declare const BOOTSTRAP_MODULE = "\0svelterm:bootstrap";
+export declare const WS_STUB_MODULE = "\0svelterm:ws-stub";
+/** Debug-server dependency, never active in bundles. */
+export declare const WS_STUB_SOURCE: string;
+/**
+ * Append a registration call so the compiled component carries its
+ * extracted CSS into the bundle; run() collects it from the registry.
+ */
+export declare function withCssRegistration(compiledJs: string, css: string | null): string;
+/**
+ * The bundle's entry module: global CSS registers first (so component
+ * styles land later in the cascade), then the app component mounts.
+ */
+export declare function bootstrapModule(entryPath: string, globalCss?: string): string;
+/** The module registering the project's global stylesheet. */
+export declare function globalCssModule(css: string): string;
+/** The conventional entry component, or null if none exists. */
+export declare function findEntry(projectDir: string): string | null;
+/** The conventional global stylesheet, or null if none exists. */
+export declare function findGlobalCss(projectDir: string): string | null;

package/dist/src/cli/bundle.js

@@ -0,0 +1,61 @@
+/**
+ * Pure helpers behind `svelterm build` — the parts that don't need
+ * rolldown: code generation for the bundle and project-layout discovery.
+ */
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+export const GLOBAL_CSS_MODULE = '\0svelterm:global-css';
+export const BOOTSTRAP_MODULE = '\0svelterm:bootstrap';
+export const WS_STUB_MODULE = '\0svelterm:ws-stub';
+/** Debug-server dependency, never active in bundles. */
+export const WS_STUB_SOURCE = [
+    'export default undefined',
+    'export class WebSocketServer {}',
+    'export class WebSocket {}',
+    '',
+].join('\n');
+/**
+ * Append a registration call so the compiled component carries its
+ * extracted CSS into the bundle; run() collects it from the registry.
+ */
+export function withCssRegistration(compiledJs, css) {
+    if (!css)
+        return compiledJs;
+    return compiledJs
+        + `\nimport { registerComponentCss as __svelterm_registerCss } from '@svelterm/core/app'`
+        + `\n__svelterm_registerCss(${JSON.stringify(css)})\n`;
+}
+/**
+ * The bundle's entry module: global CSS registers first (so component
+ * styles land later in the cascade), then the app component mounts.
+ */
+export function bootstrapModule(entryPath, globalCss) {
+    const lines = [`import { run } from '@svelterm/core/app'`];
+    if (globalCss)
+        lines.push(`import ${JSON.stringify('svelterm:global-css')}`);
+    lines.push(`import App from ${JSON.stringify(entryPath)}`, `run(App, {})`, '');
+    return lines.join('\n');
+}
+/** The module registering the project's global stylesheet. */
+export function globalCssModule(css) {
+    return `import { registerComponentCss } from '@svelterm/core/app'\n`
+        + `registerComponentCss(${JSON.stringify(css)})\n`;
+}
+const ENTRY_CANDIDATES = ['src/App.svelte', 'App.svelte'];
+const GLOBAL_CSS_CANDIDATES = ['src/main.css', 'main.css'];
+/** The conventional entry component, or null if none exists. */
+export function findEntry(projectDir) {
+    return firstExisting(projectDir, ENTRY_CANDIDATES);
+}
+/** The conventional global stylesheet, or null if none exists. */
+export function findGlobalCss(projectDir) {
+    return firstExisting(projectDir, GLOBAL_CSS_CANDIDATES);
+}
+function firstExisting(dir, candidates) {
+    for (const candidate of candidates) {
+        const full = path.join(dir, candidate);
+        if (existsSync(full))
+            return full;
+    }
+    return null;
+}

package/dist/src/cli/dev.d.ts

@@ -0,0 +1,10 @@
+/**
+ * svelterm dev — connects to a Vite dev server and runs the
+ * terminal app. The server compiles modules, this process
+ * renders to the terminal.
+ *
+ * Usage:
+ *   npx svelterm dev http://localhost:5173
+ *   npx svelterm dev http://localhost:5173/src/App.svelte
+ */
+export declare function runDev(argv: string[]): Promise<void>;

package/dist/src/cli/dev.js

@@ -0,0 +1,152 @@
+/**
+ * svelterm dev — connects to a Vite dev server and runs the
+ * terminal app. The server compiles modules, this process
+ * renders to the terminal.
+ *
+ * Usage:
+ *   npx svelterm dev http://localhost:5173
+ *   npx svelterm dev http://localhost:5173/src/App.svelte
+ */
+import { ModuleRunner, createWebSocketModuleRunnerTransport } from 'vite/module-runner';
+import { WebSocket } from 'ws';
+import http from 'http';
+export async function runDev(argv) {
+    const url = argv[0];
+    if (!url) {
+        console.error('Usage: svelterm dev http://localhost:5173');
+        process.exit(1);
+    }
+    const parsedUrl = new URL(url);
+    const baseUrl = `${parsedUrl.protocol}//${parsedUrl.host}`;
+    const wsUrl = `ws://${parsedUrl.host}/__svelterm`;
+    const ws = new WebSocket(wsUrl);
+    await new Promise((resolve, reject) => {
+        ws.on('open', resolve);
+        ws.on('error', reject);
+    });
+    const transport = createWebSocketModuleRunnerTransport({
+        createConnection() {
+            return ws;
+        },
+    });
+    const runner = new ModuleRunner({ transport });
+    // Discover entry from the server config, or use the URL path
+    let entry;
+    if (parsedUrl.pathname !== '/') {
+        entry = parsedUrl.pathname;
+    }
+    else {
+        const serverConfig = await fetchJson(`${baseUrl}/__svelterm/config`);
+        if (!serverConfig) {
+            console.error('svelterm not configured on this server.');
+            console.error('Add svelterm.terminalServer() to your vite plugins.');
+            process.exit(1);
+        }
+        entry = '/' + serverConfig.entry.replace(/^\.\//, '');
+    }
+    let cleanup = null;
+    let restartTimer = null;
+    async function startApp() {
+        if (cleanup) {
+            try {
+                cleanup();
+            }
+            catch { }
+            cleanup = null;
+        }
+        try {
+            // Clear evaluated modules for fresh imports
+            const mods = runner.evaluatedModules;
+            if (mods?.idToModuleMap) {
+                mods.idToModuleMap.clear();
+            }
+            const mod = await runner.import(entry);
+            const Component = mod.default;
+            if (!Component) {
+                console.error(`${entry} must default-export a Svelte component`);
+                return;
+            }
+            const sveltermMod = await runner.import('@svelterm/core/app');
+            const css = await fetchText(`${baseUrl}/__svelterm/css`) ?? '';
+            cleanup = sveltermMod.run(Component, {
+                css,
+                fullscreen: true,
+                mouse: true,
+                // The terminal is the app's screen — route console output
+                // to the dev server pane instead, like a browser console.
+                onConsole(entry) {
+                    if (ws.readyState !== ws.OPEN)
+                        return;
+                    ws.send(JSON.stringify({
+                        type: 'custom',
+                        event: 'svelterm:console',
+                        data: { level: entry.level, text: entry.args.join(' ') },
+                    }));
+                },
+            });
+        }
+        catch (err) {
+            console.error('[svelterm] Error:', err);
+        }
+    }
+    function scheduleRestart() {
+        if (restartTimer)
+            clearTimeout(restartTimer);
+        restartTimer = setTimeout(() => {
+            restartTimer = null;
+            startApp();
+        }, 100);
+    }
+    // Listen for HMR updates from the server
+    ws.on('message', (data) => {
+        try {
+            const msg = JSON.parse(data.toString());
+            if (msg.type === 'update' || msg.type === 'full-reload') {
+                scheduleRestart();
+            }
+        }
+        catch { }
+    });
+    await startApp();
+    process.on('SIGINT', () => {
+        if (cleanup)
+            cleanup();
+        runner.close();
+        ws.close();
+        process.exit(0);
+    });
+    process.on('SIGTERM', () => {
+        if (cleanup)
+            cleanup();
+        runner.close();
+        ws.close();
+        process.exit(0);
+    });
+    // Keep the process alive on the WebSocket + terminal input.
+    await new Promise((resolve) => ws.on('close', resolve));
+}
+function fetchJson(url) {
+    return new Promise((resolve) => {
+        http.get(url, (res) => {
+            let data = '';
+            res.on('data', (chunk) => data += chunk);
+            res.on('end', () => {
+                try {
+                    resolve(JSON.parse(data));
+                }
+                catch {
+                    resolve(null);
+                }
+            });
+        }).on('error', () => resolve(null));
+    });
+}
+function fetchText(url) {
+    return new Promise((resolve) => {
+        http.get(url, (res) => {
+            let data = '';
+            res.on('data', (chunk) => data += chunk);
+            res.on('end', () => resolve(data));
+        }).on('error', () => resolve(null));
+    });
+}

package/dist/src/cli/devtools.d.ts

@@ -0,0 +1,9 @@
+/**
+ * svelterm devtools — launch the DevTools TUI, a svelterm app that
+ * connects to a running app's debug server and inspects its live tree,
+ * styles, and layout.
+ *
+ *   svelterm devtools            # connect on 9444
+ *   svelterm devtools --port 9500
+ */
+export declare function runDevtools(argv: string[]): Promise<void>;

package/dist/src/cli/devtools.js

@@ -0,0 +1,47 @@
+/**
+ * svelterm devtools — launch the DevTools TUI, a svelterm app that
+ * connects to a running app's debug server and inspects its live tree,
+ * styles, and layout.
+ *
+ *   svelterm devtools            # connect on 9444
+ *   svelterm devtools --port 9500
+ */
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { fileURLToPath } from 'node:url';
+export async function runDevtools(argv) {
+    const port = extractPort(argv);
+    const here = path.dirname(fileURLToPath(import.meta.url));
+    const compiledPath = path.resolve(here, '../devtools/DevTools.compiled.js');
+    const cssPath = path.resolve(here, '../devtools/DevTools.css.js');
+    let DevTools;
+    let css = '';
+    try {
+        DevTools = (await import(pathToFileURL(compiledPath).href)).default;
+        css = (await import(pathToFileURL(cssPath).href)).css ?? '';
+    }
+    catch {
+        console.error('DevTools component is not compiled. Reinstall @svelterm/core.');
+        process.exit(1);
+    }
+    // Import run() the same way a consumer's app does, so the renderer
+    // instance matches the compiled component's.
+    const require = createRequire(path.join(process.cwd(), 'package.json'));
+    let run;
+    try {
+        run = require('@svelterm/core/app').run;
+    }
+    catch {
+        const mod = await import('../index.js');
+        run = mod.run;
+    }
+    run(DevTools, { css, props: { port } });
+}
+function extractPort(argv) {
+    for (let i = 0; i < argv.length; i++) {
+        if (argv[i] === '--port')
+            return Number(argv[i + 1]) || 9444;
+    }
+    return 9444;
+}

package/dist/src/cli/init.d.ts

@@ -0,0 +1,8 @@
+/**
+ * svelterm init — scaffold a terminal app project:
+ *
+ *   npx svelterm init my-app
+ */
+export declare function runInit(argv: string[]): void;
+/** Create the project files; throws if the directory has content. */
+export declare function scaffoldProject(dir: string): void;

package/dist/src/cli/init.js

@@ -0,0 +1,153 @@
+/**
+ * svelterm init — scaffold a terminal app project:
+ *
+ *   npx svelterm init my-app
+ */
+import { existsSync, mkdirSync, readdirSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+export function runInit(argv) {
+    const target = argv[0];
+    if (!target) {
+        console.error('Usage: svelterm init <directory>');
+        process.exit(1);
+    }
+    const dir = path.resolve(target);
+    try {
+        scaffoldProject(dir);
+    }
+    catch (err) {
+        console.error(err instanceof Error ? err.message : String(err));
+        process.exit(1);
+    }
+    console.log(`Scaffolded ${path.basename(dir)}. Next:`);
+    console.log(`  cd ${target}`);
+    console.log('  # see README.md — svelterm needs the custom-renderer Svelte fork');
+    console.log('  npm install && npm run dev');
+}
+/** Create the project files; throws if the directory has content. */
+export function scaffoldProject(dir) {
+    if (existsSync(dir) && readdirSync(dir).length > 0) {
+        throw new Error(`${dir} is not empty — refusing to scaffold over existing files`);
+    }
+    mkdirSync(path.join(dir, 'src'), { recursive: true });
+    const name = path.basename(dir);
+    for (const [file, content] of Object.entries(templates(name))) {
+        writeFileSync(path.join(dir, file), content);
+    }
+}
+function templates(name) {
+    return {
+        'package.json': JSON.stringify({
+            name,
+            private: true,
+            version: '0.0.0',
+            type: 'module',
+            scripts: {
+                dev: 'vite dev',
+                app: 'svelterm dev http://localhost:5173',
+                build: 'svelterm build',
+            },
+            dependencies: {
+                '@svelterm/core': '^0.4.0',
+                // The custom-renderer Svelte branch — see the scaffolded README
+                svelte: 'file:../svelte-fork/packages/svelte',
+            },
+            devDependencies: {
+                rolldown: '^1.0.0',
+                vite: '^7.0.0',
+            },
+        }, null, 4) + '\n',
+        'vite.config.ts': `import { defineConfig } from 'vite'
+import { svelterm } from '@svelterm/core/vite'
+
+// Terminal-only app — svelterm's plugins compile .svelte for the
+// terminal environment; no vite-plugin-svelte needed. (Dual-target
+// browser + terminal setups do need it — see
+// https://svelterm.dev/docs/getting-started.)
+export default defineConfig({
+    plugins: [
+        ...svelterm.terminalServer({ entry: './src/App.svelte' }),
+    ],
+    environments: svelterm.environments(),
+    optimizeDeps: { exclude: ['svelte'] },
+    ssr: { noExternal: ['svelte'] },
+})
+`,
+        'src/App.svelte': `<script>
+    let count = $state(0)
+</script>
+
+<div class="app">
+    <span class="title">${name}</span>
+    <span>Count: <span class="value">{count}</span></span>
+    <button onclick={() => count++}>Increment</button>
+    <button onclick={() => count--}>Decrement</button>
+</div>
+
+<style>
+    .app {
+        display: flex;
+        flex-direction: column;
+        gap: 1cell;
+        border: rounded;
+        border-color: cyan;
+        padding: 1cell 2cell;
+    }
+
+    .title {
+        font-weight: bold;
+    }
+
+    .value {
+        color: yellow;
+        font-weight: bold;
+    }
+
+    button {
+        width: 20cell;
+    }
+
+    button:focus {
+        color: cyan;
+        font-weight: bold;
+    }
+</style>
+`,
+        'src/main.css': `/* Global styles — component <style> blocks layer on top. */
+`,
+        '.gitignore': `node_modules/
+dist/
+`,
+        'README.md': `# ${name}
+
+A terminal app built with [svelterm](https://svelterm.dev).
+
+## Prerequisites
+
+svelterm needs the Svelte custom-renderer branch (unmerged upstream).
+Clone and build it as a sibling of this project:
+
+\`\`\`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
+\`\`\`
+
+## Develop
+
+\`\`\`bash
+npm install
+npm run dev    # vite dev server (terminal 1)
+npm run app    # the app, in this terminal (terminal 2)
+\`\`\`
+
+Edits hot-reload; \`console.log\` output appears in the vite terminal.
+
+## Ship
+
+\`\`\`bash
+npm run build  # → dist/app.mjs, runnable with plain node
+node dist/app.mjs
+\`\`\`
+`,
+    };
+}

package/dist/src/cli/main.d.ts

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+/**
+ * svelterm — the CLI. Subcommands:
+ *
+ *   svelterm init <dir>          scaffold a terminal app project
+ *   svelterm dev <url>           run the app against a Vite dev server
+ *   svelterm build [entry]       bundle into one self-contained .mjs
+ */
+export {};

package/dist/src/cli/main.js

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+/**
+ * svelterm — the CLI. Subcommands:
+ *
+ *   svelterm init <dir>          scaffold a terminal app project
+ *   svelterm dev <url>           run the app against a Vite dev server
+ *   svelterm build [entry]       bundle into one self-contained .mjs
+ */
+const USAGE = `Usage:
+  svelterm init <directory>
+  svelterm dev <dev-server-url>[/path/to/App.svelte]
+  svelterm build [entry.svelte] [-o out.mjs] [--css main.css]
+  svelterm inspect <tree|query|style|box|console|raw> [args] [--port n]
+  svelterm devtools [--port n]`;
+async function main() {
+    const [command, ...rest] = process.argv.slice(2);
+    switch (command) {
+        case 'init': {
+            const { runInit } = await import('./init.js');
+            runInit(rest);
+            break;
+        }
+        case 'dev': {
+            const { runDev } = await import('./dev.js');
+            await runDev(rest);
+            break;
+        }
+        case 'build': {
+            const { runBuild } = await import('./build.js');
+            await runBuild(rest);
+            break;
+        }
+        case 'inspect': {
+            const { runSvt } = await import('./svt.js');
+            await runSvt(rest);
+            break;
+        }
+        case 'devtools': {
+            const { runDevtools } = await import('./devtools.js');
+            await runDevtools(rest);
+            break;
+        }
+        default:
+            console.error(USAGE);
+            process.exit(command === undefined || command === '--help' ? 0 : 1);
+    }
+}
+main().catch((err) => {
+    console.error('Fatal:', err);
+    process.exit(1);
+});
+export {};

package/dist/src/cli/svt-bin.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/src/cli/svt-bin.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+import { runSvt } from './svt.js';
+runSvt(process.argv.slice(2)).catch((err) => {
+    console.error(err.message ?? String(err));
+    process.exit(1);
+});

package/dist/src/cli/svt.d.ts

@@ -0,0 +1,14 @@
+/**
+ * svt — debug-protocol client. Connects to a `run(App, { debug: true })`
+ * app's WebSocket server, sends one request, prints the JSON result.
+ *
+ *   svt tree                       # DOM.getDocument
+ *   svt query '.card'              # DOM.querySelector
+ *   svt style <nodeId>             # CSS.getComputedStyle
+ *   svt box <nodeId>               # DOM.getBoxModel
+ *   svt console                    # Console.getEntries
+ *   svt raw DOM.getDocument '{}'   # any method + JSON params
+ *
+ *   --port <n>   debug server port (default 9444)
+ */
+export declare function runSvt(argv: string[]): Promise<void>;

package/dist/src/cli/svt.js

@@ -0,0 +1,76 @@
+/**
+ * svt — debug-protocol client. Connects to a `run(App, { debug: true })`
+ * app's WebSocket server, sends one request, prints the JSON result.
+ *
+ *   svt tree                       # DOM.getDocument
+ *   svt query '.card'              # DOM.querySelector
+ *   svt style <nodeId>             # CSS.getComputedStyle
+ *   svt box <nodeId>               # DOM.getBoxModel
+ *   svt console                    # Console.getEntries
+ *   svt raw DOM.getDocument '{}'   # any method + JSON params
+ *
+ *   --port <n>   debug server port (default 9444)
+ */
+import { WebSocket } from 'ws';
+export async function runSvt(argv) {
+    const { rest, port } = extractPort(argv);
+    const command = buildCommand(rest);
+    if (!command) {
+        printUsage();
+        process.exit(1);
+    }
+    const result = await request(port, command);
+    process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+}
+function buildCommand(argv) {
+    const [verb, ...args] = argv;
+    switch (verb) {
+        case 'tree': return { method: 'DOM.getDocument', params: {} };
+        case 'query': return { method: 'DOM.querySelector', params: { selector: args[0] } };
+        case 'style': return { method: 'CSS.getComputedStyle', params: { nodeId: Number(args[0]) } };
+        case 'box': return { method: 'DOM.getBoxModel', params: { nodeId: Number(args[0]) } };
+        case 'console': return { method: 'Console.getEntries', params: { count: Number(args[0]) || 100 } };
+        case 'raw': return { method: args[0], params: args[1] ? JSON.parse(args[1]) : {} };
+        default: return null;
+    }
+}
+function request(port, command) {
+    return new Promise((resolve, reject) => {
+        const ws = new WebSocket(`ws://127.0.0.1:${port}`);
+        const timer = setTimeout(() => { ws.close(); reject(new Error('timed out')); }, 3000);
+        ws.on('open', () => ws.send(JSON.stringify({ id: 1, ...command })));
+        ws.on('message', (data) => {
+            clearTimeout(timer);
+            const msg = JSON.parse(data.toString());
+            ws.close();
+            if (msg.error)
+                reject(new Error(msg.error.message));
+            else
+                resolve(msg.result);
+        });
+        ws.on('error', () => {
+            clearTimeout(timer);
+            reject(new Error(`cannot connect on port ${port} — run the target app with run(App, { debug: true })`));
+        });
+    });
+}
+function extractPort(argv) {
+    const rest = [];
+    let port = 9444;
+    for (let i = 0; i < argv.length; i++) {
+        if (argv[i] === '--port')
+            port = Number(argv[++i]) || port;
+        else
+            rest.push(argv[i]);
+    }
+    return { rest, port };
+}
+function printUsage() {
+    console.error(`Usage: svt <command> [--port <n>]
+  tree                 print the node tree
+  query <selector>     find a node id by CSS selector
+  style <nodeId>       computed style for a node
+  box <nodeId>         layout box for a node
+  console [count]      recent console entries
+  raw <method> [json]  any protocol method with JSON params`);
+}

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

@@ -1,3 +1,4 @@
+import { nextGraphemeBoundary, prevGraphemeBoundary } from '../layout/unicode.js';
 export class TextBuffer {
     _text;
     _cursor;
@@ -18,16 +19,18 @@ export class TextBuffer {
     delete() {
         if (this._cursor >= this._text.length)
             return;
-        this._text = this._text.substring(0, this._cursor) + this._text.substring(this._cursor + 1);
+        const end = nextGraphemeBoundary(this._text, this._cursor);
+        this._text = this._text.substring(0, this._cursor) + this._text.substring(end);
     }
     backspace() {
         if (this._cursor <= 0)
             return;
-        this._text = this._text.substring(0, this._cursor - 1) + this._text.substring(this._cursor);
-        this._cursor--;
+        const start = prevGraphemeBoundary(this._text, this._cursor);
+        this._text = this._text.substring(0, start) + this._text.substring(this._cursor);
+        this._cursor = start;
     }
-    moveLeft() { this.cursor--; }
-    moveRight() { this.cursor++; }
+    moveLeft() { this._cursor = prevGraphemeBoundary(this._text, this._cursor); }
+    moveRight() { this._cursor = nextGraphemeBoundary(this._text, this._cursor); }
     home() { this._cursor = 0; }
     end() { this._cursor = this._text.length; }
     clearToStart() {