@svelterm/core 0.1.0 → 0.23.0

package/docs/guide/theming.md

@@ -0,0 +1,94 @@
+# Theming
+
+Svelterm uses CSS variables for theming — the same mechanism as the web. Define color tokens on a root element, reference them throughout your components, switch themes by changing a class.
+
+## Basic theme
+
+```css
+:root {
+    --primary: cyan;
+    --accent: yellow;
+    --muted: gray;
+    --bg: black;
+    --fg: white;
+}
+
+.title { color: var(--primary); }
+.value { color: var(--accent); }
+.hint { color: var(--muted); opacity: dim; }
+```
+
+## Multiple themes
+
+Define theme palettes as class selectors. Switch by changing the class on a parent element:
+
+```svelte
+<script>
+    let theme = $state('dark-ocean')
+</script>
+
+<style>
+    .dark-ocean {
+        --primary: cyan; --accent: yellow; --border: cyan;
+    }
+    .dark-forest {
+        --primary: green; --accent: yellow; --border: green;
+    }
+    .light-paper {
+        --primary: #2244aa; --accent: #886600; --border: #2244aa;
+    }
+</style>
+
+<div class="app {theme}">
+    <span style:color="var(--primary)">{theme}</span>
+    <button onclick={() => theme = 'dark-forest'}>Switch</button>
+</div>
+```
+
+## Light and dark mode
+
+Svelterm detects the terminal's background color via OSC 11 at startup, then polls every second. The detected scheme feeds into `@media (prefers-color-scheme)`:
+
+```css
+@media (prefers-color-scheme: dark) {
+    :root { --bg: black; --fg: white; --primary: cyan; }
+}
+
+@media (prefers-color-scheme: light) {
+    :root { --bg: #eeeeee; --fg: #111111; --primary: #0088aa; }
+}
+```
+
+This works automatically — no code needed. If the user switches their terminal's color scheme, the app re-renders with the correct palette within a second.
+
+### Color contrast
+
+Some CSS colors have poor contrast on light backgrounds (yellow, cyan, gold). Use the media query to provide darker variants:
+
+```css
+.warning { color: yellow; }
+
+@media (prefers-color-scheme: light) {
+    .warning { color: #997700; }
+}
+```
+
+## Dual-target theming
+
+CSS variables work in both terminal and browser. Use the same tokens, with target-specific values:
+
+```css
+:root {
+    --primary: cyan;
+    --bg: black;
+}
+
+@media (display-mode: screen) {
+    :root {
+        --primary: #00b4d8;
+        --bg: #1a1a2e;
+    }
+}
+```
+
+The terminal gets ANSI `cyan`. The browser gets hex `#00b4d8`. Same component, same variable names, different rendered values.

package/docs/how-it-works.md

@@ -0,0 +1,115 @@
+# How it works
+
+svelterm is a Svelte custom renderer plus a CSS engine plus a terminal
+painter. There is no DOM anywhere — not emulated, not shimmed. This page
+walks the path from your component source to ANSI bytes on a terminal.
+
+## No DOM
+
+Svelte's compiler doesn't hardcode the DOM: compiled components call a
+renderer interface — create an element, insert a node, set an attribute,
+set text, listen for an event. In a browser that interface is backed by
+`document`. svelterm (via the experimental
+[custom renderer API](https://github.com/paoloricciuti/svelte/tree/svelte-custom-renderer))
+supplies a different backing: every call builds and mutates a tree of
+**`TermNode`** objects — plain values holding a tag, attributes, children,
+event listeners, and a little render cache. No `document`, no `window`, no
+JSDOM.
+
+Everything Svelte does — reactivity, `$state`, effects, `{#if}`/`{#each}`
+patching, component composition, scoped styles — works unchanged, because
+Svelte only ever asks the renderer to make small tree mutations. Your
+component doesn't know it's in a terminal; a handful of DOM-compat
+properties on `TermNode` (`textContent`, `nodeValue`, `checked`, `value`)
+cover the places Svelte's generated code reads nodes directly.
+
+The renderer itself is stateless; each node carries its render context
+(`node.ctx`), attached on insert and cleared on remove, so trees can be
+built detached and adopted later.
+
+## The pipeline
+
+Each frame runs a browser-shaped pipeline against the `TermNode` tree,
+with one radical simplification: the unit of geometry is a character
+cell, not a pixel.
+
+```
+component source
+      │ svelte compiler (customRenderer)
+      ▼
+  TermNode tree  ◄── Svelte reactivity mutates it
+      │ resolve styles      cascade, specificity, selectors, var(), @media
+      ▼
+  ResolvedStyle per node
+      │ layout              block/inline flow, flex, grid, tables → cells
+      ▼
+  LayoutBox per node        { x, y, width, height } in cells
+      │ paint               borders, text, backgrounds, form glyphs
+      ▼
+  CellBuffer                every cell: { char, fg, bg, bold, … }
+      │ diff vs previous buffer
+      ▼
+  minimal ANSI              cursor moves + SGR codes, sync-wrapped
+```
+
+- **Style resolution** matches the stylesheet's selectors against the
+  tree and folds the cascade into one `ResolvedStyle` struct per element
+  — the same job as a browser's computed style, minus pixel-derived
+  properties (which parse and drop; see
+  [compatibility](./compatibility.md)).
+- **Layout** implements block/inline flow, flexbox, grid, and table
+  algorithms over integer cells. Every length rounds to whole cells;
+  borders are one cell thick.
+- **Paint** writes glyphs and colours into a `CellBuffer` — including
+  box-drawing borders, list markers, form-control glyphs like `[x]`, and
+  `::before`/`::after` runs.
+- **Diff** compares against the previous buffer and emits only the
+  changed cells as ANSI (cursor positioning + colour codes), wrapped in
+  a synchronized-update sequence so the terminal repaints atomically.
+
+## Incremental updates
+
+Re-running the whole pipeline per keystroke would waste most of its
+work, so mutations are classified at the point Svelte makes them:
+
+- same-length text change → **paint only**
+- attribute change → **re-resolve styles** for the node and its
+  descendants (any attribute can affect selector matching)
+- size-affecting change → **layout**, scoped to a subtree or bubbled to
+  the nearest fixed-size ancestor
+
+A microtask-batched queue coalesces a burst of mutations into one
+render, which runs only the stages the batch needs — an incremental
+style pass, an incremental layout pass, and a repaint clipped to the
+damaged region.
+
+## Input, without a browser
+
+Raw stdin bytes are parsed into key events (including modifiers and
+escape sequences), SGR mouse events with cell coordinates, and
+bracketed paste. Mouse positions hit-test against the layout boxes to
+find the target node; events then dispatch through the tree with
+W3C capture/bubble semantics, `preventDefault()` and all. Focus is a
+document-order traversal of focusable elements driven by `Tab`, with
+`:focus`/`:hover` implemented as attribute-backed pseudo-classes.
+Default actions (link opening, checkbox toggling, select cycling,
+label activation) live in the run loop, mirroring browser behaviour.
+
+## Time
+
+An animation clock discovers elements whose resolved style declares an
+animation or whose transition targets changed, applies the current
+interpolated values onto their resolved styles (~30fps), and enqueues
+paint-only or layout invalidation per frame depending on what the
+animation touches — see [motion](./motion.md).
+
+## The terminal is an interface too
+
+All output goes through a small `TerminalIO` interface rather than
+`process.stdout` directly. `ProcessIO` backs real terminals (raw mode,
+alternate screen, resize signals, OSC 11 colour-scheme queries);
+`InProcessIO` backs anything that can accept a byte stream — which is
+how the playground works: the same engine, compiled for the browser,
+writes its ANSI into an xterm.js instance. The browser pane next to it
+is simply the same component compiled with Svelte's normal DOM renderer.
+One source, two render targets — that contrast is the whole point.

package/docs/inline-mode.md

@@ -0,0 +1,77 @@
+# Inline mode
+
+Fullscreen apps own the alternate screen. CLI tools want the opposite:
+output that streams downward, scrolls into the terminal's real
+scrollback, and leaves the screen intact on exit — the Claude Code /
+Gemini CLI shape. That's inline mode:
+
+```typescript
+run(App, { mode: 'inline' })
+```
+
+The app renders at the shell's cursor position in the main buffer. The
+**live area** sizes itself to the app's content (clamped to the terminal
+height) and updates with cell-level diffs; everything above it belongs to
+the terminal and is never touched again. All cursor movement is relative
+— svelterm never needs to know where on the screen it's running. On exit
+the rendered output stays put and the shell prompt continues below it.
+
+## FrameLog
+
+The companion for streaming sessions: an append-only log of frames,
+each a mounted component. Archiving a finished frame hands its rows to
+the terminal's scrollback and unmounts the component — memory tracks
+what's live, not the whole session.
+
+```svelte
+<script>
+    import { createFrameLog } from '@svelterm/core/app'
+    import Message from './Message.svelte'
+
+    function start(el) {
+        const log = createFrameLog(el)
+        const run = setTimeout(async () => {
+            log.append(Message, { role: 'user', text: 'hello' })
+            const props = $state({ role: 'assistant', text: '', streaming: true })
+            const id = log.append(Message, props)
+            for await (const chunk of stream()) props.text += chunk
+            props.streaming = false
+            log.archive(id)   // this turn scrolls into history, components freed
+        }, 0)
+        return () => clearTimeout(run)
+    }
+</script>
+
+<div class="log" {@attach start}></div>
+<StatusBar />
+```
+
+- **`append(Component, props)`** mounts a frame and returns its id. Pass
+  a `$state` object as props to stream updates into it (mutate it, or
+  call `update(id, partial)` which assigns onto the same object).
+- **`archive(id)`** archives every frame up to and including `id` —
+  frames leave from the top, in order. Their rows stay on the terminal
+  exactly as rendered.
+- **`remove(id)`** deletes a frame outright (redaction); the live area
+  reflows to close the gap.
+- Get the host element with `{@attach ...}` — `bind:this` is not
+  available under the custom renderer. Kick off async work with
+  `setTimeout(fn, 0)` so state writes don't re-trigger the attachment.
+
+Try it: `DEMO=inline npm run demo` in the svelterm repo.
+
+## Constraints
+
+- The live area must fit the terminal height — archive finished content
+  to keep it short. Content past the bottom clips.
+- **Mouse works in the live area**: the zone's screen position comes
+  from a cursor-position query, so clicks, hover, and scroll map into
+  the app; clicks on shell history above it are ignored. (On a terminal
+  that doesn't answer CPR, mouse events are dropped.) Keyboard input,
+  focus, and the input cursor work as usual.
+- Archived rows never re-wrap: after a resize they keep their old
+  wrapping, like any other scrollback. The live area re-lays-out and
+  repaints in place on width changes (best effort — some terminals
+  re-wrap the live rows too; the next frame repaints them).
+- Every change re-renders the live area fully (it's content-sized, so
+  anything can move). Keep live frames modest; archive the rest.

package/docs/layout.md

@@ -0,0 +1,112 @@
+# Layout
+
+svelterm implements the CSS layout models that make sense on a cell grid:
+block/inline flow, flexbox, grid, tables, and positioning. Lengths are
+cells; behaviour follows the specs linked below unless a grid deviation is
+noted.
+
+## Box model
+
+[Box model](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_box_model)
+as standard: `width`/`height` (+ `min-`/`max-`), `padding`, `margin`
+(including `margin: auto` centring and vertical
+[margin collapse](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_box_model/Mastering_margin_collapsing)),
+`box-sizing: border-box | content-box`. Borders are 1 cell thick when
+present.
+
+`overflow: hidden | scroll | auto` clips, and scrollable boxes really
+scroll — mouse wheel, with fading scrollbar overlays. `text-overflow:
+ellipsis` needs the usual `white-space: nowrap; overflow: hidden`.
+
+Scrolling is O(visible): subtrees outside the clip are culled from the
+paint walk, so a 10,000-row list repaints in ~1.5 ms per scroll step
+(initial layout still visits every row once). No windowing API needed —
+put long content in an `overflow: auto` box and scroll it.
+
+When the whole viewport scrolls (a fullscreen list, streaming inline
+output), the diff detects the vertical translation and emits a DECSTBM
+scroll-region command instead of rewriting every cell — an 80×40 screen
+scrolled one line is ~13× less output, which shows on slow links.
+
+## Display and flow
+
+`display: block, inline, inline-block, flex, grid, none, contents` and
+the full set of table display types. Inline elements flow horizontally
+and wrap; whitespace between inline siblings is preserved, between block
+siblings collapsed — matching browser text flow.
+
+## Flexbox
+
+[Flexbox](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_flexible_box_layout)
+support: `flex-direction` (all four), `flex-wrap`, the `flex` shorthand
+and `flex-grow`/`flex-shrink`/`flex-basis`, `gap`, `justify-content`
+(including the `space-*` distributions), `align-items`, `align-self`,
+`order`.
+
+```css
+.toolbar { display: flex; gap: 1ch; justify-content: space-between; }
+.spacer  { flex: 1; }
+```
+
+## Grid
+
+[Grid](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_grid_layout)
+support:
+
+- `grid-template-columns` / `grid-template-rows` with `cell`/`ch`, `%`,
+  `fr`, `repeat()`, and `minmax()`.
+- Placement: `grid-column` and `grid-row` (`start`, `start / end`,
+  `span n`), numeric `grid-area` (`r1 / c1 / r2 / c2`).
+- Named areas: `grid-template-areas` with `grid-area: name`; `.` is a
+  hole; a repeated name spans its rectangle. Without a column template,
+  areas split the width evenly.
+
+```css
+.app {
+    display: grid;
+    grid-template-columns: 20ch 1fr;
+    grid-template-rows: 1ch 1fr 1ch;
+    grid-template-areas:
+        "header header"
+        "nav    main"
+        "footer footer";
+}
+.nav { grid-area: nav; }
+```
+
+Deviations: auto-flow is row-based (`grid-auto-flow: column` is not
+implemented); `minmax()` minimums on `fr` tracks are enforced without
+redistribution; spanning content doesn't stretch individual tracks.
+
+## Tables
+
+Full [CSS table layout](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_table):
+`<table>`/`<thead>`/`<tbody>`/`<tfoot>`/`<caption>`/`<colgroup>`,
+`colspan`/`rowspan`, `table-layout: auto | fixed`, `border-spacing`,
+`caption-side`, `empty-cells`, and `border-collapse: collapse` drawn with
+shared box-drawing grid lines. Anonymous boxes are generated for stray
+content. `vertical-align: baseline` is treated as `top` (one line of
+cells has no baseline distinct from its top).
+
+## Positioning
+
+`position: absolute` and `fixed` take elements out of flow and place them
+by `top`/`right`/`bottom`/`left` with `z-index` stacking. `position:
+relative` shifts the element (and its descendants) visually while the
+flow behaves as if it hadn't moved, per spec. `position: sticky` pins an
+element to the top of its scroll container once scrolled past
+(`top`-edge only; it doesn't yet push out at the end of its containing
+block, and hit-testing targets the flow position rather than the stuck
+one). A sticky element with a transparent background shows scrolled
+content through it — give it a background. Sub-cell geometry
+(`transform`, floats) is out of scope; see
+[compatibility](./compatibility.md).
+
+## Sizing behaviours worth knowing
+
+- Blocks fill their container's width; inline-blocks shrink-wrap.
+- `input`/`textarea`/`select` have a minimum height of one row;
+  `<select>` sizes to its longest option plus the `▾` indicator;
+  checkboxes/radios are 3×1; `progress`/`meter` default to 20×1.
+- `@container` size queries evaluate against the nearest laid-out
+  ancestor, in cells.

package/docs/motion.md

@@ -0,0 +1,91 @@
+# Animations and transitions
+
+CSS motion works on the grid with one honest constraint: a cell either
+has a glyph and colours or it doesn't. Colours interpolate smoothly;
+geometry steps cell by cell; everything else switches discretely.
+
+## Animations
+
+[`@keyframes`](https://developer.mozilla.org/en-US/docs/Web/CSS/@keyframes)
+with `from`/`to` or percentage stops, driven by the `animation` shorthand
+or `animation-name` / `animation-duration` / `animation-iteration-count`
+(including `infinite`) / `animation-timing-function`:
+
+```css
+@keyframes pulse {
+    0%  { color: #ef4444; }
+    50% { color: #7f1d1d; }
+}
+.recording { animation: pulse 1s ease-in-out infinite; }
+```
+
+Keyframe values resolve
+[`var()`](https://developer.mozilla.org/en-US/docs/Web/CSS/var) and
+[`light-dark()`](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value/light-dark)
+against the animated element when the animation starts.
+
+## Easing
+
+[`animation-timing-function`](https://developer.mozilla.org/en-US/docs/Web/CSS/animation-timing-function)
+and
+[`transition-timing-function`](https://developer.mozilla.org/en-US/docs/Web/CSS/transition-timing-function)
+support `linear`, `ease` (the default, as in browsers), `ease-in`,
+`ease-out`, `ease-in-out`, `cubic-bezier(x1, y1, x2, y2)`,
+`steps(n[, start | end])`, `step-start` and `step-end`. As in CSS, the
+easing shapes progress within each keyframe segment, and non-interpolable
+values switch when *eased* progress crosses the midpoint.
+
+## What interpolates
+
+- **Colours** (`color`, `background`) mix in RGB at ~30fps between the
+  surrounding stops. ANSI palette names interpolate through nominal
+  values and stay exact at the endpoints.
+- **Single cell/ch lengths** (`width`, `height`, `padding-*`, `margin-*`,
+  insets, `gap`) interpolate and round to whole cells — a 10-cell slide
+  is ten visible steps, so give movement enough distance to read.
+- **Everything else** supported by the style system (`display`,
+  `font-weight`, `border-*`, `visibility`, …) applies discretely,
+  switching at the midpoint of the segment — the CSS rule for
+  non-interpolable values.
+
+Layout-affecting animations re-flow every frame; colour-only animations
+just repaint.
+
+## Transitions
+
+[`transition`](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_transitions)
+runs when a tracked property's target changes — a class toggles, an
+inline style updates, a `:checked` rule starts applying:
+
+```css
+.preview { transition: background-color 400ms; }
+.tab     { transition: color 150ms, padding-left 150ms; }
+```
+
+`transition-property` takes a list or `all`; `transition-duration` takes
+`ms`/`s`. The same interpolation rules as animations apply. The initial
+style never transitions.
+
+## Deviations from browsers
+
+- One duration and one timing function apply to all listed transition
+  properties (per-property lists aren't split).
+- An interrupted transition restarts from its previous target value, not
+  the current blended value.
+- `opacity` doesn't interpolate (it applies discretely mid-animation) —
+  animate colour toward the background for a smooth fade.
+- Keyframe `var()`/`light-dark()` resolution happens once when the
+  animation starts; changing a custom property doesn't retarget a
+  running animation.
+- Per-keyframe `animation-timing-function` overrides are ignored — the
+  element's timing function applies to every segment.
+
+## Reduced motion
+
+Media queries work, so honour user preference the standard way:
+
+```css
+@media (prefers-reduced-motion: reduce) {
+    .recording { animation: none; }
+}
+```

package/docs/reference/README.md

@@ -0,0 +1,65 @@
+# Svelterm Reference
+
+Authoritative reference for svelterm's authoring surface and runtime APIs.
+
+## Layout
+
+```
+docs/reference/
+├── css/
+│   ├── properties/    # Per-property pages (border-style, padding, …)
+│   ├── units/         # Unit pages (cell, %, …)
+│   ├── at-rules/      # @media, @keyframes, …
+│   └── selectors.md   # Selector reference
+├── runtime/           # run(), IO, Terminal, …
+└── integration/       # Svelte integration, custom renderer, …
+```
+
+## Page conventions
+
+Each page is a standalone Markdown file with the following structure:
+
+```markdown
+---
+name: border-style
+category: css/properties
+summary: Controls the visual appearance of the element's border.
+related:
+  - css/properties/border-corner
+  - css/properties/border-color
+---
+
+# `border-style`
+
+One-line description.
+
+## Syntax
+
+(Or `## Values` for properties with a fixed value list.)
+
+## Examples
+
+Each example shows the CSS, then the resulting terminal output (ASCII frame inline; later: actual rendered image).
+
+## Notes
+
+Caveats, terminal-vs-browser differences, edge cases.
+
+## See also
+
+Cross-links to related pages.
+```
+
+## Visual examples
+
+Examples should include a small terminal "frame" rendered as Markdown so the page is readable as plain text. The site build can later replace these with real rendered images.
+
+```
+┌─────────────┐
+│ hello       │
+└─────────────┘
+```
+
+## Stable surface
+
+Documented properties, values, and APIs are part of svelterm's stable surface. Behaviour changes need a corresponding doc update.

package/docs/reference/css/properties/border-corner.md

@@ -0,0 +1,82 @@
+---
+name: border-corner
+category: css/properties
+summary: Controls which axis owns the corner cells of a block-character border.
+related:
+  - css/properties/border-style
+---
+
+# `border-corner`
+
+Block-character border styles (`eighth-cell-*`, `half-cell-*`) have no Unicode glyph that combines two perpendicular strokes in a single cell. `border-corner` selects which axis "owns" the corner cells.
+
+## Values
+
+| Value | Effect |
+|-------|--------|
+| `none` | Default. Corner cells blank — produces a soft-rounded look. |
+| `h` | Top/bottom strokes extend through corner cells. Side strokes stop one cell short. |
+| `v` | Left/right strokes extend through corner cells. Top/bottom stop one cell short. |
+
+Only meaningful for [`border-style`](border-style.md) values in the `*-cell-*` family. Box-drawing styles (`single`, `double`, `rounded`, `heavy`) have proper corner glyphs and ignore this property.
+
+## Examples
+
+### `border-corner: none` (default)
+
+```css
+.box {
+    border-style: eighth-cell-inner;
+}
+```
+
+```
+ ▁▁▁▁▁▁▁▁▁▁▁▁
+▕            ▏
+ ▔▔▔▔▔▔▔▔▔▔▔▔
+```
+
+Corners blank; the box reads as soft-rounded.
+
+### `border-corner: h`
+
+```css
+.box {
+    border-style: eighth-cell-inner;
+    border-corner: h;
+}
+```
+
+```
+▁▁▁▁▁▁▁▁▁▁▁▁▁▁
+              
+ ▔▔▔▔▔▔▔▔▔▔▔▔
+```
+
+Top/bottom strokes own the corners; sides indent by one.
+
+### `border-corner: v`
+
+```css
+.box {
+    border-style: eighth-cell-inner;
+    border-corner: v;
+}
+```
+
+```
+ ▁▁▁▁▁▁▁▁▁▁▁▁
+▕            ▏
+▕            ▏
+ ▔▔▔▔▔▔▔▔▔▔▔▔
+```
+
+Side strokes own the corners; top/bottom indent by one.
+
+## Notes
+
+- `border-corner` is per-element; mixing per-side `border-style` values does not change which axis owns the corner.
+
+## See also
+
+- [`border-style`](border-style.md)