@svelterm/core 0.1.0 → 0.21.0

package/dist/src/vite/config.js

@@ -0,0 +1,191 @@
+/**
+ * Vite configuration helpers for svelterm.
+ *
+ * Usage in vite.config.ts:
+ *
+ *   import { svelte } from '@sveltejs/vite-plugin-svelte'
+ *   import { svelterm } from '@svelterm/core/vite'
+ *
+ *   export default defineConfig({
+ *       plugins: [
+ *           svelte(svelterm.svelteOptions()),
+ *           ...svelterm.terminalServer(),
+ *       ],
+ *       environments: svelterm.environments(),
+ *   })
+ *
+ * Then in another terminal:
+ *   npx svelterm dev http://localhost:5173/src/App.svelte
+ */
+import { createRunnableDevEnvironment } from 'vite';
+/**
+ * Returns svelte plugin options with dynamicCompileOptions for the
+ * terminal environment.
+ */
+export function svelteOptions(config = {}) {
+    const renderer = config.renderer ?? '@svelterm/core';
+    return {
+        dynamicCompileOptions({ environment }) {
+            if (environment === 'terminal') {
+                return {
+                    generate: 'client',
+                    css: 'external',
+                    experimental: {
+                        customRenderer: renderer,
+                    },
+                };
+            }
+        },
+    };
+}
+/**
+ * Returns Vite environment configuration for the terminal environment.
+ */
+export function environments() {
+    return {
+        terminal: {
+            dev: {
+                createEnvironment(name, config) {
+                    return createRunnableDevEnvironment(name, config);
+                },
+            },
+            resolve: {
+                conditions: ['svelte', 'node'],
+                // Everything svelte-adjacent must flow through the module
+                // runner — a natively-imported copy of svelte or the
+                // renderer would be a second instance with its own state,
+                // and mount would silently build an empty tree.
+                noExternal: ['svelte', '@svelterm/core'],
+            },
+        },
+    };
+}
+/**
+ * Returns Vite plugins that bridge the terminal environment over
+ * WebSocket and serve CSS for the svelterm CLI.
+ */
+export function terminalServer(config = {}) {
+    const rendererModule = config.renderer ?? '@svelterm/core';
+    let wss;
+    let WS;
+    return [{
+            // Compile .svelte for the terminal environment ourselves —
+            // vite-plugin-svelte is not environment-aware (it emits an empty
+            // stub for non-client environments), and terminal-only projects
+            // shouldn't need the environment-aware plugin fork.
+            name: 'svelterm:terminal-svelte',
+            enforce: 'pre',
+            async transform(code, id) {
+                if (!id.endsWith('.svelte'))
+                    return null;
+                const environment = this.environment;
+                if (environment?.name !== 'terminal')
+                    return null;
+                const { compile } = await import('svelte/compiler');
+                const compiled = compile(code, {
+                    generate: 'client',
+                    css: 'external',
+                    filename: id,
+                    experimental: { customRenderer: rendererModule },
+                });
+                const css = compiled.css?.code;
+                const registration = css
+                    ? `\nimport { registerComponentCss as __svelterm_registerCss } from '@svelterm/core/app'`
+                        + `\n__svelterm_registerCss(${JSON.stringify(css)})\n`
+                    : '';
+                return { code: compiled.js.code + registration, map: null };
+            },
+        }, {
+            name: 'svelterm:server',
+            apply: 'serve',
+            async configResolved() {
+                const ws = await import('ws');
+                WS = ws.WebSocket;
+                wss = new ws.WebSocketServer({ noServer: true });
+            },
+            configureServer(server) {
+                // Discovery endpoint
+                server.middlewares.use('/__svelterm/config', (_req, res) => {
+                    res.setHeader('Content-Type', 'application/json');
+                    res.end(JSON.stringify({
+                        version: 1,
+                        entry: config.entry ?? './App.svelte',
+                        renderer: rendererModule,
+                    }));
+                });
+                // CSS endpoint — re-compiles .svelte files to extract CSS
+                server.middlewares.use('/__svelterm/css', async (_req, res) => {
+                    const env = server.environments?.terminal;
+                    if (!env) {
+                        res.end('');
+                        return;
+                    }
+                    const parts = [];
+                    const { compile } = await import('svelte/compiler');
+                    const fs = await import('fs');
+                    for (const mod of env.moduleGraph?.idToModuleMap?.values() ?? []) {
+                        if (mod.id?.endsWith('.svelte') && !mod.id.includes('?')) {
+                            try {
+                                const source = fs.readFileSync(mod.id, 'utf-8');
+                                const result = compile(source, {
+                                    css: 'external',
+                                    filename: mod.id,
+                                    experimental: { customRenderer: rendererModule },
+                                });
+                                if (result.css?.code) {
+                                    parts.push(result.css.code);
+                                }
+                            }
+                            catch { }
+                        }
+                    }
+                    res.setHeader('Content-Type', 'text/css');
+                    res.end(parts.join('\n'));
+                });
+                // WebSocket bridge for ModuleRunner
+                server.httpServer?.on('upgrade', (req, socket, head) => {
+                    if (req.url === '/__svelterm') {
+                        wss.handleUpgrade(req, socket, head, (ws) => {
+                            const env = server.environments?.terminal;
+                            if (!env) {
+                                ws.close();
+                                return;
+                            }
+                            const client = {
+                                send(payload) {
+                                    if (ws.readyState === WS.OPEN) {
+                                        ws.send(JSON.stringify(payload));
+                                    }
+                                },
+                            };
+                            ws.on('message', (data) => {
+                                try {
+                                    const msg = JSON.parse(data.toString());
+                                    if (msg.type === 'ping')
+                                        return;
+                                    if (msg.type === 'custom' && msg.event === 'svelterm:console') {
+                                        // The app's console output — the terminal
+                                        // shows the app, so logs surface here.
+                                        const { level, text } = msg.data ?? {};
+                                        server.config.logger.info(`[svelterm] console.${level}: ${text}`);
+                                        return;
+                                    }
+                                    if (msg.type === 'custom' && msg.event) {
+                                        env.hot.api?.innerEmitter?.emit(msg.event, msg.data, client);
+                                    }
+                                }
+                                catch { }
+                            });
+                            const forward = (payload) => client.send(payload);
+                            env.hot.api?.outsideEmitter?.on('send', forward);
+                            client.send({ type: 'connected' });
+                            ws.on('close', () => {
+                                env.hot.api?.outsideEmitter?.off('send', forward);
+                            });
+                        });
+                    }
+                });
+            },
+        }];
+}
+export const svelterm = { svelteOptions, environments, terminalServer };

package/docs/compatibility.md

@@ -0,0 +1,67 @@
+# Browser compatibility
+
+The rule: **any HTML/CSS feature with a sensible meaning on a grid of
+character cells works the way a browser author expects.** Features with
+no grid meaning parse and are silently dropped — never a crash, never a
+half-render. The test of "sensible" is whether the feature survives the
+move from pixels to cells: structure, cascade, selectors, layout, colour,
+and state all do; sub-cell geometry does not.
+
+## The three buckets
+
+1. **Implemented faithfully** — spec behaviour on the cell grid. This is
+   most of what pasted browser CSS touches; the other chapters document
+   it and the [reference](./reference.md) tabulates it.
+2. **Approximated, documented** — the concept maps but the grid forces a
+   compromise. Each approximation is deliberate and tested:
+   - 1 cell is the atom: every length rounds to whole cells.
+   - `opacity < 1` ≈ the terminal *dim* attribute (binary).
+   - `vertical-align: baseline` ≈ `top` in tables.
+   - `<select>` is a popup-less cycling control — a dropdown has no good
+     cell-grid answer.
+   - Animation is linear (no easing) and lengths step by whole cells.
+3. **Out of scope** — dropped silently, styled per mode instead.
+
+## The ignored list
+
+Pixel-derived lengths (`px`, `em`, `rem`, `ex`, `vw`, `vh`) ·
+typography (`font-size`, `font-family`, `line-height`,
+`letter-spacing`, `word-spacing`) · sub-cell decoration
+(`border-radius`, `box-shadow`, `outline`, `filter`,
+`backdrop-filter`) · geometry (`transform`, `rotate`, `scale`,
+`translate`, `perspective`) · `background-image` and gradients ·
+`float` · `@font-face`, `@page` · easing keywords.
+
+## The pattern
+
+Style each mode on its own terms with
+[`display-mode`](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/display-mode)
+blocks — svelterm matches `terminal`, real browsers apply the `browser`
+block as ordinary CSS:
+
+```css
+.card {
+    padding: 1ch;                      /* shared — 1ch is 1 cell */
+    @media (display-mode: browser) {
+        border: 1px solid #ddd;
+        border-radius: 8px;
+        box-shadow: 0 2px 8px #0002;
+    }
+    @media (display-mode: terminal) {
+        border: rounded;
+    }
+}
+```
+
+Because the ignored list drops rather than errors, a component pasted
+from a website renders sensibly with **zero terminal-specific CSS** —
+the shadows and radii simply don't appear until you add terminal styling.
+
+## Where this is pinned down
+
+- [`reference.md`](./reference.md) — the one-page support matrix.
+- `DESIGN-browser-compat.md` in the repo root — the design rationale and
+  slice history.
+- The acceptance tests (`test/browser-compat-acceptance.test.ts`) keep
+  both promises honest: a website-flavoured card renders with no
+  terminal CSS, and every ignored declaration parses without effect.

package/docs/debug/devtools.md

@@ -0,0 +1,40 @@
+# DevTools
+
+`svelterm devtools` is a terminal DevTools — itself a svelterm app — that
+connects to a running app's debug server and inspects its live tree,
+computed styles, and layout.
+
+## Use
+
+Run the app you want to inspect with `debug: true`:
+
+```ts
+run(App, { css, debug: true })   // debug server on 127.0.0.1:9444
+```
+
+Then, in another terminal (or tmux pane):
+
+```bash
+svelterm devtools               # connect on 9444
+svelterm devtools --port 9500   # a non-default port
+```
+
+- **Left pane** — the node tree, indented by depth, each row labelled
+  `<div#id.class>` / `"text"` / `<!--comment-->`.
+- **Right pane** — the selected node's computed style (the values
+  svelterm actually painted) and its layout box.
+- **↑ / ↓** move the selection, **← / →** collapse / expand a subtree
+  (Enter toggles), **r** refreshes the tree, **Ctrl+C** quits.
+
+The style panel lists every non-default resolved value for the selected
+element.
+
+It talks the same JSON protocol as the [`svt`](./svt.md) one-shot client
+(the `DOM` and `CSS` domains), so it works against any app that opens a
+debug server — including one running over ssh, if you forward the port.
+
+## Note
+
+Like the debug server itself, DevTools needs a real `ws` — it inspects
+apps run from source or via `svelterm dev`, not `svelterm build` bundles
+(which stub `ws` out).

package/docs/debug/svt.md

@@ -0,0 +1,50 @@
+# svt — debug CLI
+
+`svt` connects to a running svelterm app's debug server (a WebSocket on
+`127.0.0.1`) and inspects its live node tree, styles, and layout from the
+command line. Also available as `svelterm inspect`. For an interactive
+terminal inspector, see [DevTools](./devtools.md).
+
+## Enabling debug mode
+
+Run the app with `debug: true`:
+
+```ts
+run(App, {
+    css,
+    debug: true,        // start the debug server
+    debugPort: 9444,    // optional, default 9444
+})
+```
+
+The server binds to `127.0.0.1` only. (Note: `svelterm build` bundles
+stub out `ws`, so the debug server is a no-op in a shipped bundle — run
+from source, or via `svelterm dev`, to inspect.)
+
+## Commands
+
+```bash
+svt tree                 # print the whole node tree (tags, attrs, text)
+svt query '.card'        # find a node id by CSS selector
+svt style <nodeId>       # the resolved computed style svelterm painted
+svt box <nodeId>         # the node's layout box (x, y, width, height)
+svt console [count]      # recent console entries
+svt raw DOM.getDocument '{}'   # any protocol method + JSON params
+svt query '.card' --port 9500  # non-default port
+```
+
+Output is JSON on stdout — pipe it through `jq`:
+
+```bash
+svt query '.card' | jq .nodeId
+svt style "$(svt query '.card' | jq .nodeId)" | jq '.style | {fg, width, borderStyle}'
+```
+
+## Protocol
+
+The server speaks a small JSON-over-WebSocket protocol: a request is
+`{ id, method, params }`, a reply `{ id, result }` or `{ id, error }`.
+Domains: `DOM` (`getDocument`, `querySelector`, `getBoxModel`,
+`setAttribute`, `removeAttribute`), `CSS` (`getComputedStyle`), and
+`Console` (`getEntries`, `clear`). `svt raw <method> <json>` reaches any
+of them, so tooling can build on the same channel.

package/docs/distribution.md

@@ -0,0 +1,106 @@
+# Shipping terminal apps
+
+The playground proves components in a browser-hosted emulator; this page
+is about the other half — running the same code in real terminals, and
+packaging it so other people can.
+
+## Try it: the playground demos in your terminal
+
+Every playground example is also published as a single self-contained
+module:
+
+```bash
+curl -fsSL https://svelterm.dev/run/counter.mjs | node --input-type=module -
+```
+
+(`https://svelterm.dev/run.txt` lists them all.) The `.mjs` has the
+component, its CSS, svelterm, and the Svelte runtime bundled flat — the
+only requirement is Node 20+.
+
+Piping a script into `node -` normally costs you interactivity, because
+stdin *is* the script. svelterm's `ProcessIO` handles this: when stdin is
+not a TTY it reopens the controlling terminal (`/dev/tty`) for input, so
+Tab/Enter/mouse keep working. On Windows (no `/dev/tty`), download first:
+`curl -o app.mjs … && node app.mjs`.
+
+## Bundling an app
+
+The demo endpoint is also the reference recipe
+(`svelterm-site/scripts/build-demos.mjs`): compile the component with the
+custom renderer, wrap it in a `run()` bootstrap, and bundle for Node.
+The shape, with any bundler (rolldown shown; esbuild works the same way):
+
+```js
+// 1. compile — terminal variant
+const { js, css } = compile(source, {
+    generate: 'client',
+    css: 'external',
+    experimental: { customRenderer: '@svelterm/core' },
+})
+
+// 2. bootstrap
+//   import App from './App.js'
+//   import { run } from '@svelterm/core/app'
+//   run(App, { css: <extracted css string> })
+
+// 3. bundle: platform node, single-file ESM output
+const bundle = await rolldown({ input: 'entry.js', platform: 'node' })
+await bundle.write({ format: 'esm', file: 'app.mjs', codeSplitting: false })
+```
+
+In a Vite project, `@svelterm/core/vite` configures the compiler side for
+you; the bundle step is the same. Result: one `.mjs`, ~350 kB, no
+`node_modules` at runtime.
+
+## Distribution options
+
+**A URL** — host the `.mjs` anywhere static and document the `curl | node -`
+line. Zero install, easiest to keep current; requires Node on the
+machine. This is what svelterm.dev/run does.
+
+**An npm package** — point `bin` at a small launcher that imports your
+bundle, and users run `npx your-app` (or install it globally). Works
+wherever npm does; versioning and updates come free.
+
+```json
+{ "name": "your-app", "bin": { "your-app": "./app.mjs" }, "engines": { "node": ">=20" } }
+```
+
+(Add `#!/usr/bin/env node` at the top of the bundle for the bin path.)
+
+**A single executable** — bundle the runtime in, so users need nothing:
+
+- `bun build --compile app.mjs --outfile your-app` produces a per-platform
+  binary (~90 MB).
+- Node's [single executable applications](https://nodejs.org/api/single-executable-applications.html)
+  inject the bundle into a copied `node` binary.
+- `deno compile` similarly, via Deno's Node compatibility.
+
+These are documented paths rather than tested ones — the `.mjs` bundles
+are what svelterm exercises today (Node 20+, verified on macOS/Linux
+terminals). Bun and Deno run Node-flavoured code well and the bundles
+avoid native dependencies entirely, but treat them as "should work,
+verify" until the test matrix says otherwise.
+
+## What svelterm needs from a terminal
+
+Any reasonably modern emulator qualifies: raw mode, cursor addressing,
+and 16-colour ANSI at minimum. Truecolor is used when hex colours appear
+(near-universal now); mouse support needs SGR mouse mode; synchronized
+updates are used when available and harmless when not. The alternate
+screen buffer hosts fullscreen apps (`fullscreen: false` opts out).
+Windows Terminal covers all of this on Windows.
+
+## A testing story for real terminals
+
+Three layers, increasing in realism:
+
+1. **Headless** — `@svelterm/core/headless` renders components to cell
+   buffers in plain Node for unit tests; svelterm's own thousand-test
+   suite runs this way.
+2. **The playground** — visual verification in the browser emulator,
+   side by side with the DOM render.
+3. **The bundles** — pipe a demo (or your own app's bundle) into a real
+   terminal. This is scriptable too: run the bundle inside `tmux`, drive
+   it with `tmux send-keys`, assert on `tmux capture-pane` — a real
+   PTY, real escape-sequence parsing, no emulator in the loop.

package/docs/elements.md

@@ -0,0 +1,120 @@
+# Elements, input and events
+
+What HTML renders to on the grid, how form controls behave, and how
+events reach your handlers. Anything unlisted renders as a plain box per
+its display default.
+
+## Text and structure
+
+Headings, paragraphs, lists (`ul`/`ol` with markers), `blockquote`,
+`pre`, `hr` (a `─` rule), `figure`, `dl`, and the text-level elements
+(`strong`/`b`, `em`/`i`, `u`, `s`/`del`, `mark`, `code`, `kbd`, `abbr`,
+`samp`, `var`) carry a browser-like UA stylesheet in cells. `img`,
+`video`, `canvas`, and `iframe` are not rendered (inline images are a
+planned, separate feature).
+
+## Images
+
+`<img src="...">` renders as half-blocks — each cell shows two vertically
+stacked pixels ('▀' with per-half colours), so a 40×20-pixel image is
+40 columns × 10 rows. Sources: file paths and `data:image/png;base64`
+URIs (PNG: 8-bit RGB/RGBA/greyscale/palette, decoded with no native
+dependencies). Sizing follows CSS `width`/`height` in cells, defaulting
+to the intrinsic pixel size; loading is async and reflows on arrival.
+Mostly-transparent pixels show the terminal background.
+
+On terminals that speak the [kitty graphics protocol](https://sw.kovidgoyal.net/kitty/graphics-protocol/)
+(kitty, Ghostty, WezTerm — detected automatically), the image renders as
+real pixels scaled to its cell box, covering the half-blocks. Everywhere
+else the half-blocks are what you see.
+
+## Links
+
+`<a>` is underlined and focusable. `Enter` or a click fires `click`; if
+unprevented, the `href` opens in the local browser.
+
+## Form controls
+
+| Control | Rendering | Interaction |
+|---|---|---|
+| `input` (text) | one-row editor on the grid | readline-style editing with a real cursor; `input` events carry `{ value, cursor }` |
+| `textarea` | multi-line editor | as above |
+| `input type="checkbox"` | `[x]` / `[ ]` (3×1) | `Space` or click toggles; `change`/`input` carry `{ checked, value }` |
+| `input type="radio"` | `(•)` / `( )` | selecting unchecks same-`name` radios across the tree; never untoggles itself |
+| `select` + `option`/`optgroup` | selected label + `▾`, sized to the longest option | popup-less cycling: `ArrowUp`/`ArrowDown` move with wraparound, `Space`/`Enter`/click advance; `change` carries `{ value }` |
+| `button` | centred text, stylable | `Enter`/click dispatch `click` |
+| `progress` / `meter` | 20×1 block bar: `█` fill, eighth-block partials, `░` track | `value`/`max` (+`min` for meter); no value = indeterminate track |
+| `details` / `summary` | ▶/▼ disclosure marker | `Enter`/click toggles `open`; fires `toggle` with `{ open }`; closed details hide non-summary children |
+| `label` | plain inline text | clicking activates its control — wrapping or `for="id"` both work |
+
+State attributes drive selectors: `:checked`, `:disabled`/`:enabled`,
+`[open]`. `disabled` controls are skipped by focus traversal and swallow
+clicks. DOM-compat properties exist where Svelte bindings expect them:
+`el.checked`, `el.value`.
+
+## Focus
+
+`Tab` / `Shift+Tab` cycle `button`, `input`, `textarea`, `a`, `select`,
+`summary` in document order, skipping disabled controls. Clicking a
+focusable element focuses it. The focused element matches
+[`:focus`](https://developer.mozilla.org/en-US/docs/Web/CSS/:focus) —
+style it; there is no default focus ring beyond your CSS.
+
+```css
+button:focus { border-color: yellow; }
+```
+
+## Keyboard
+
+- `Enter` — activate the focused element (click / toggle / cycle).
+- `Space` — toggle checkbox/radio, advance select.
+- Arrows — cycle selects; move the text cursor in inputs.
+- Printable keys — type into the focused input/textarea.
+- Unhandled keys dispatch `keydown` to the focused element (or the tree
+  root) with `{ key, ctrl, shift, meta }`.
+- `Ctrl+C` exits (add `'ctrl+d'` to `run`'s `exitOn` for EOF-style
+  exit). `Ctrl+Z` truly suspends: the terminal is restored for the
+  shell, and `fg` re-enters modes and repaints with state intact.
+- The [kitty keyboard protocol](https://sw.kovidgoyal.net/kitty/keyboard-protocol/)
+  is enabled where supported, so combinations the legacy encoding can't
+  express (`Ctrl+Enter`, `Shift+Space`, …) arrive with correct
+  modifiers. Elsewhere the classic encoding applies.
+
+## Modal dialogs
+
+A `<dialog open>` captures input like a browser modal:
+`Tab`/`Shift+Tab` trap inside it, focus is pulled in from outside, and
+`Escape` removes `open` and dispatches a `close` event. Style it with
+`position: absolute` + `z-index` to float above the page.
+
+```svelte
+{#if confirming}
+    <dialog open onclose={() => confirming = false}>
+        <span>Delete everything?</span>
+        <button onclick={confirm}>Yes</button>
+        <button onclick={() => confirming = false}>No</button>
+    </dialog>
+{/if}
+```
+
+## Mouse
+
+Enabled by default: click (focus + click + default action), wheel
+scrolling of `overflow: auto|scroll` boxes (with scrollbar overlays),
+hover driving `:hover`. Mouse events carry cell coordinates.
+
+## The event model
+
+Events dispatch with W3C capture/bubble semantics through the component
+tree; `stopPropagation()` and `preventDefault()` work, and default
+actions (link opening, details toggling, select cycling, label
+activation) respect `preventDefault()`.
+
+Payloads ride on `event.data` — `{ value, cursor }` for text input,
+`{ checked, value }` for checkables, `{ open }` for toggle,
+`{ cols, rows }` for region resize. Handlers shared with the browser
+should read both shapes:
+
+```svelte
+<select onchange={(e) => plan = e.data?.value ?? e.target.value}>
+```