@svelterm/core 0.1.0 → 0.23.0

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

@@ -0,0 +1,168 @@
+---
+name: border-style
+category: css/properties
+summary: Controls the visual appearance of an element's border.
+related:
+  - css/properties/border-corner
+  - css/properties/border-color
+  - css/properties/padding
+  - css/properties/margin
+---
+
+# `border-style`
+
+Selects which characters render the four edges of an element's border. Two families: **box-drawing** (thin strokes through the cell centre) and **block-character** (strips on a chosen edge of each cell). Block-character styles compose cleanly with `background-color`; box-drawing styles do not.
+
+## Values
+
+| Value | Family | Composes with `background-color` |
+|-------|--------|----------------------------------|
+| `none` | — | n/a |
+| `single` | box-drawing | no |
+| `double` | box-drawing | no |
+| `rounded` | box-drawing | no |
+| `heavy` | box-drawing | no |
+| `eighth-cell-inner` | block-character | yes |
+| `eighth-cell-outer` | block-character | yes |
+| `half-cell-inner` | block-character | yes |
+| `half-cell-outer` | block-character | yes |
+| `full-cell` | block-character | n/a (no bg shows) |
+
+The `*-cell-inner` variants paint a strip on the **inner** edge of each border cell (facing the content). The `*-cell-outer` variants paint on the **outer** edge.
+
+## Box-drawing styles
+
+`single`, `double`, `rounded`, `heavy` use Unicode box-drawing characters (`┌─┐│└┘`, `╔═╗║╚╝`, `╭─╮│╰╯`, `┏━┓┃┗┛`). The stroke runs through the centre of each cell and the surrounding cell area takes the cell's `background-color`.
+
+```
+┌──────────────┐
+│ hello        │
+└──────────────┘
+```
+
+When the element has a coloured `background-color`, the bg fills the gap around the stroke — the border looks like it's floating in a coloured frame rather than at the box edge. For coloured boxes with a visible border, prefer `*-cell-inner` instead.
+
+## Block-character styles
+
+### `eighth-cell-inner`
+
+1/8-cell stroke on the inner edge of each border cell. Faces the content. Corner cells are blank.
+
+```
+ ▁▁▁▁▁▁▁▁▁▁▁▁
+▕            ▏
+▕            ▏
+ ▔▔▔▔▔▔▔▔▔▔▔▔
+```
+
+Combined with `background-color`, the 7/8 of each border cell that isn't the stroke takes the bg colour — the fill extends right up to the stroke.
+
+### `eighth-cell-outer`
+
+Same 1/8 stroke, but on the outer edge of each border cell. Faces away from the content.
+
+### `half-cell-inner` / `half-cell-outer`
+
+Same model with 1/2-cell strokes (`▄▀▐▌`). Thicker, more visible.
+
+### `full-cell`
+
+Each border cell is painted entirely with `█` in the border colour. The thickest visible option; no portion of the border cell shows the cell `background-color`.
+
+## Corner behaviour
+
+Block-character styles have no glyph that combines two perpendicular strokes in one cell. By default corner cells are left blank (soft-rounded look). Use [`border-corner`](border-corner.md) to make one axis own the corners instead.
+
+| `border-corner` | Effect on `*-cell-*` styles |
+|-----------------|------------------------------|
+| `none` (default) | Corners blank |
+| `h` | Top/bottom strokes extend through corners; sides stop one cell short |
+| `v` | Left/right strokes extend through corners; top/bottom stop one cell short |
+
+Box-drawing styles have proper corner glyphs and ignore `border-corner`.
+
+## Padding/margin collapse
+
+`*-cell-*` borders have a side-asymmetric "natural gap" — the unused 7/8 (or 1/2) of each border cell. To avoid this gap visually doubling with explicit `padding`/`margin`, the unused side **collapses into** the corresponding box-model value:
+
+- The border cell occupies 1 cell of layout regardless of facing direction.
+- The "spacer" side (opposite the stroke) absorbs **1 cell** of explicit padding or margin on that side.
+- `*-inner` borders absorb `margin`. `*-outer` borders absorb `padding`.
+
+### `eighth-cell-outer` with varying `padding`
+
+| CSS | Visual outcome |
+|-----|----------------|
+| `padding: 0` | Content sits right behind the stroke (no gap) |
+| `padding: 1cell` | The 1-cell border cell *is* the padding. No extra cells beyond it. |
+| `padding: 2cell` | 1 extra cell of padding beyond the border cell. |
+
+### `eighth-cell-inner` with varying `margin`
+
+| CSS | Visual outcome |
+|-----|----------------|
+| `margin: 0` | Border cell sits right against the next box (no outer gap) |
+| `margin: 1cell` | The 1-cell border cell *is* the margin. No extra cells beyond it. |
+| `margin: 2cell` | 1 extra cell of margin beyond the border cell. |
+
+In short: explicit `padding`/`margin` specifies the *total* visual space on that side, with the border cell counting toward it.
+
+## Examples
+
+### Coloured box with thin border
+
+```css
+.box {
+    background-color: #b00;
+    border-color: #0f0;
+    border-style: eighth-cell-inner;
+    padding: 0;
+}
+```
+
+```
+ ▁▁▁▁▁▁▁▁▁▁▁▁
+▕            ▏
+▕            ▏
+ ▔▔▔▔▔▔▔▔▔▔▔▔
+```
+
+### Decorative thin border (no fill)
+
+```css
+.box {
+    border-style: rounded;
+    border-color: #888;
+}
+```
+
+```
+╭──────────────╮
+│              │
+│              │
+╰──────────────╯
+```
+
+### Block frame with corner ownership
+
+```css
+.box {
+    border-style: half-cell-inner;
+    border-color: #fff;
+    border-corner: h;
+}
+```
+
+Top and bottom rows extend through the corners; sides stop one cell short.
+
+## Notes
+
+- The `*-cell-*` styles use Unicode block characters (U+2580–U+259F). These are widely supported in modern terminal fonts.
+- `full-cell` is essentially a thick painted frame — useful for highlighting but ignores the bg colour entirely.
+- Per-side border styles are supported (e.g. `border-top: eighth-cell-inner; border-bottom: half-cell-inner`). Corners follow the `border-corner` setting regardless of mixed styles.
+
+## See also
+
+- [`border-corner`](border-corner.md) — corner ownership for block-character borders
+- [`border-color`](border-color.md) — colour of the border stroke
+- [`padding`](padding.md), [`margin`](margin.md) — interact with the collapse rule above

package/docs/reference.md

@@ -0,0 +1,227 @@
+# svelterm feature reference
+
+svelterm renders Svelte components to a terminal cell grid with HTML/CSS
+semantics. This is the authoritative list of what is supported, what is
+approximated, and what is deliberately ignored. Standard features link to
+MDN rather than re-explaining them; terminal-specific behaviour is
+documented in full here.
+
+**The rule:** any feature with a sensible meaning on a grid of character
+cells works the way a browser author expects. Features with no cell-grid
+meaning (pixels, fonts, sub-cell geometry) parse and are silently dropped —
+never a crash. Target modes separately with
+`@media (display-mode: terminal)` / `@media (display-mode: browser)`.
+
+---
+
+## Terminal-specific extensions
+
+These do not exist in browsers and are svelterm's own surface.
+
+### The `cell` unit
+
+One terminal cell — the atomic unit of layout. `width: 20cell`,
+`padding: 1cell 2cell`. [`ch`](https://developer.mozilla.org/en-US/docs/Web/CSS/length#ch)
+is accepted as an exact alias (1ch = 1cell), which lets stylesheets work in
+both modes. All lengths round to whole cells. Unitless `0` is valid.
+
+### `@media (display-mode: terminal | browser)`
+
+Reuses the standard [`display-mode`](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/display-mode)
+media feature with two custom values. The terminal renderer evaluates
+`terminal` as true; real browsers never match either custom value, but a
+`browser` block simply applies as normal CSS there. This is the documented
+pattern for anything in the ignored bucket:
+
+```css
+.card {
+    @media (display-mode: browser)  { box-shadow: 0 2px 8px #0004; }
+    @media (display-mode: terminal) { border: single; }
+}
+```
+
+### Border styles
+
+[`border-style`](https://developer.mozilla.org/en-US/docs/Web/CSS/border-style)
+takes terminal-native values drawn with box-drawing and block glyphs
+(browser values like `solid`/`dashed` are ignored — use a `display-mode`
+block):
+
+| Value | Look |
+|---|---|
+| `single` | `┌─┐` light box drawing |
+| `double` | `╔═╗` double lines |
+| `rounded` | `╭─╮` rounded corners |
+| `heavy` | `┏━┓` heavy lines |
+| `ascii` | `+-+` plain ASCII |
+| `eighth-cell-inner` / `eighth-cell-outer` | thin eighth-block edges inside/outside the cell |
+| `half-cell-inner` / `half-cell-outer` | half-block edges |
+| `full-cell` | full-block frame |
+
+Borders are 1 cell thick. `border-top/right/bottom/left: true|false`
+enable individual sides. `border-corner: h | v | none` picks corner
+character bias. `border-color` works as standard (including
+`currentColor`).
+
+### Colour on a terminal
+
+Resolved colours are either ANSI palette names (`red`, `cyan`, …) or
+24-bit truecolor. CSS keywords that match the 8 basic ANSI names map to
+palette entries (themeable by the user's terminal); explicit hex/`rgb()`
+etc. stay exact. `transparent` means "no colour set" — the parent's
+background shows through. The terminal's own dark/light scheme is detected
+via OSC 11 polling (overridable through `run({ colorScheme })`) and drives
+[`light-dark()`](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value/light-dark)
+and `@media (prefers-color-scheme: …)`.
+
+### `opacity` ≈ `dim`
+
+There is no alpha channel. `opacity` below 1 applies the terminal's dim
+attribute; the non-standard value `opacity: dim` does the same explicitly.
+
+### `<svt-region>`
+
+A paint primitive that fills its layout box from a consumer-provided
+cell source (used to embed full terminal emulators). It fires a `resize`
+event with `{ cols, rows }` when its allocated size changes. Without an
+explicit size it fills the parent box like a replaced element.
+
+### Focus and keys
+
+`Tab`/`Shift+Tab` cycle focusable elements (`button`, `input`, `textarea`,
+`a`, `select`, `summary`); disabled controls are skipped. The focused
+element matches `:focus`. `Enter` clicks the focused element (opens `href`
+on links, toggles `<details>`, cycles `<select>`); `Space` toggles
+checkboxes/radios and cycles selects. Mouse clicks focus, click, and
+activate the same defaults. Clicking a
+[`<label>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/label)
+activates its control — wrapping or `for="id"` association both work.
+`Ctrl+C` exits.
+
+### Interaction model for form controls
+
+- **Checkbox** renders `[x]` / `[ ]`; **radio** renders `(•)` / `( )`
+  (3×1 cells). Radios group by `name` across the tree.
+- **`<select>`** is a popup-less cycling control: it renders the selected
+  option's label plus `▾`, sized to the longest option. `ArrowUp`/
+  `ArrowDown` move the selection (wrapping); `Space`/`Enter`/click advance.
+  There is no dropdown popup — it has no good cell-grid answer.
+- **`<progress>`/`<meter>`** render as 20×1 block-glyph bars (`█` fill
+  with eighth-block partials, `░` track), stylable via `color`/
+  `background`, sized via `width`/`height`.
+
+### Events
+
+W3C-style capture/bubble dispatch on the component tree: `click`,
+`keydown`, `input`, `change`, `paste`, `toggle` (details), `resize`
+(svt-region), plus mouse events with cell coordinates. Event payloads ride
+on `event.data` (e.g. `{ value, cursor }`, `{ checked }`).
+
+---
+
+## HTML elements
+
+Standard semantics unless noted. Anything unlisted renders as a plain
+block/inline box per its display default.
+
+| Element | Notes | Reference |
+|---|---|---|
+| headings, `p`, `div`, `span`, lists, `blockquote`, `pre`, `code`, `hr` | UA-styled like a browser (margins in cells, `hr` as `─` rule, list markers) | [HTML elements](https://developer.mozilla.org/en-US/docs/Web/HTML/Element) |
+| `strong`/`b`, `em`/`i`, `u`, `s`/`del`, `mark`, `kbd`, `abbr`, `samp`, `var` | text attributes (bold/italic/underline/strikethrough/colour) | — |
+| `a` | underlined, focusable; Enter/click opens `href` in the local browser | [`<a>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a) |
+| `table` and friends | full table layout: colspan/rowspan, header/footer groups, caption, `colgroup`/`col` width hints, collapse/separate borders, `empty-cells` | [`<table>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/table) |
+| `input` (text) | single-line editor with cursor, `value`, `input` events | [`<input>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input) |
+| `input type="checkbox" / "radio"` | glyph toggles; `checked` attribute/property; `change`+`input` events | [checkbox](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/checkbox), [radio](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/radio) |
+| `textarea` | multi-line editing | [`<textarea>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/textarea) |
+| `button` | focusable, centred text, `click` on Enter/click | [`<button>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button) |
+| `select`/`option`/`optgroup` | cycling control (see above); `change`+`input` with the option value | [`<select>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/select) |
+| `progress`, `meter` | block-glyph bars; `value`/`max` (+`min` for meter); no-value progress renders track only | [`<progress>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/progress), [`<meter>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/meter) |
+| `details`/`summary` | ▶/▼ disclosure, `open` attribute, `toggle` event, focusable summary | [`<details>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/details) |
+| `img` | half-block pixels (▀) from PNG file paths / `data:image/png` URIs; real pixels via the kitty graphics protocol where supported; sized by CSS `width`/`height` | [`<img>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img) |
+| `video`, `canvas`, `iframe` | not rendered | — |
+
+## CSS selectors
+
+All standard matching semantics. Reference: [MDN selectors](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_selectors).
+
+- Type, `.class`, `#id`, `*`, selector lists (`a, b`)
+- Combinators: descendant, `>`, `+`, `~`
+- Attributes: `[a]`, `[a=v]`, `[a^=v]`, `[a$=v]`, `[a*=v]`, `[a~=v]`, `[a|=v]` (quoted or unquoted values)
+- Pseudo-classes: `:root`, `:focus`, `:hover` (mouse), `:first-child`,
+  `:last-child`, `:only-child`, `:empty`, `:first-of-type`,
+  `:last-of-type`, `:only-of-type`, `:nth-child()`, `:nth-last-child()`,
+  `:nth-of-type()`, `:nth-last-of-type()` (full An+B), `:not()`, `:is()`,
+  `:where()`, `:checked`, `:disabled`, `:enabled`
+- Pseudo-elements: `::before`, `::after` (single-colon legacy accepted)
+  with `content:` strings, `attr(x)`, space-separated concatenation, and
+  `none`/`""`. `counter()` is not supported. Pseudo boxes are inline and
+  invisible to `:empty`/`:nth-*`. Known gap: pseudo-elements don't render
+  inside table-internal boxes.
+- Specificity, source order, and inline-`style` precedence follow the
+  [cascade](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_cascade/Cascade).
+
+## CSS properties
+
+Grouped; all standard behaviour (per MDN) except the noted grid
+adaptations. Lengths are cells (`cell`/`ch`, `%`, or `calc()`).
+
+| Group | Properties |
+|---|---|
+| [Colour & text](https://developer.mozilla.org/en-US/docs/Web/CSS/color) | `color`, `background`/`background-color`, `font-weight` (≥700 = bold), `font-style` (italic), `text-decoration` (underline/line-through), `text-transform`, `text-align`, `text-overflow` (`ellipsis`, plus non-standard `ellipsis-middle`), `white-space` (`normal`/`nowrap`/`pre`), `opacity` (≈dim), `visibility` |
+| [Box model](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_box_model) | `width`, `height`, `min/max-width`, `min/max-height`, `padding(-*)`, `margin(-*)` (incl. `auto` centring and margin collapse), `box-sizing`, `overflow` (`hidden`/`scroll`/`auto` with real scrolling + fading scrollbars) |
+| [Display & flow](https://developer.mozilla.org/en-US/docs/Web/CSS/display) | `display: block, inline, inline-block, flex, grid, none, contents`, all table display types |
+| [Flexbox](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_flexible_box_layout) | `flex-direction` (all four), `flex-wrap`, `flex`/`flex-grow`/`flex-shrink`/`flex-basis`, `gap`, `justify-content` (incl. `space-*`), `align-items`, `align-self`, `order` |
+| [Grid](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_grid_layout) | `grid-template-columns/rows` (`cell`/`ch`/`%`/`fr`, `repeat()`, `minmax()`), `grid-template-areas` + `grid-area` (named and numeric), `grid-column`, `grid-row` (start / start‑end / `span n`), `gap`. Auto-flow is row-based; `grid-auto-flow: column` is not implemented. Fractional `minmax()` minimums are enforced without redistribution |
+| [Positioning](https://developer.mozilla.org/en-US/docs/Web/CSS/position) | `position: static/relative/absolute/fixed/sticky` with `top/right/bottom/left`, `z-index`. Relative offsets shift visually without moving flow; sticky is top-edge only inside scroll containers (no push-out at the containing block end) |
+| [Tables](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_table) | `border-collapse`, `border-spacing`, `caption-side`, `table-layout`, `empty-cells`, `vertical-align` (`baseline` ≈ `top`) |
+| Borders | `border`/`border-style`/`border-color`/`border-corner` + per-side toggles (terminal values above) |
+| [Animation](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_animations) | `animation` shorthand, `animation-name/-duration/-iteration-count` (incl. `infinite`)/`-timing-function`, `@keyframes` (from/to/percentages, values resolve `var()`/`light-dark()`) |
+| [Transitions](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_transitions) | `transition` shorthand, `transition-property` (list or `all`), `transition-duration`, `transition-timing-function` |
+| [Easing](https://developer.mozilla.org/en-US/docs/Web/CSS/easing-function) | `linear`, `ease` (default), `ease-in`, `ease-out`, `ease-in-out`, `cubic-bezier()`, `steps()`, `step-start`, `step-end` |
+
+### Animation & transition semantics on the grid
+
+Colours interpolate in RGB at ~30fps; single cell/ch lengths interpolate
+to whole cells (movement steps cell by cell); every other supported
+property applies discretely, switching at the segment midpoint (the CSS
+rule for non-interpolable values). Layout-affecting animations re-flow
+each frame. Easing applies per keyframe segment; non-interpolable values
+switch when eased progress crosses the midpoint. Deviations: one duration
+and one timing function for all listed transition properties, interrupted
+transitions restart from the previous target value, keyframe
+`var()`/`light-dark()` resolves once at animation start, and per-keyframe
+`animation-timing-function` overrides are ignored.
+
+## Values, functions and at-rules
+
+- Units: `cell`/`ch`, `%`, unitless `0`, `fr` (grid). Everything
+  pixel-derived is dropped (see below).
+- [`var()`](https://developer.mozilla.org/en-US/docs/Web/CSS/var) custom
+  properties with inheritance and fallbacks.
+- [`calc()`](https://developer.mozilla.org/en-US/docs/Web/CSS/calc),
+  `min()`, `max()`, `clamp()` over cells and `%`.
+- Colours: hex (3/6/8 digit), `rgb()`/`rgba()`, `hsl()`/`hsla()`, `hwb()`,
+  `lab()`, `lch()`, `oklab()`, `oklch()` (legacy and modern syntax), all
+  148 named colours, `transparent`, `currentColor`,
+  [`light-dark()`](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value/light-dark).
+  Alpha composites at paint time (blends over the cell beneath), and
+  numeric `opacity` acts as a blend factor.
+- Keywords: `inherit`, `initial`, `unset`.
+- At-rules: [`@media`](https://developer.mozilla.org/en-US/docs/Web/CSS/@media)
+  (`prefers-color-scheme`, `display-mode`, `min/max-width`, `min/max-height`
+  — in cells), [`@container`](https://developer.mozilla.org/en-US/docs/Web/CSS/@container)
+  (size queries against the nearest laid-out ancestor),
+  [`@supports`](https://developer.mozilla.org/en-US/docs/Web/CSS/@supports)
+  (property-name checks), `@keyframes`. Nested rules inside declarations
+  (`& {}`-less media nesting) are supported.
+
+## Ignored (no cell-grid meaning)
+
+These parse and are dropped silently. Use `@media (display-mode: browser)`
+for the browser-side styling and a terminal-native equivalent if needed.
+
+`px`/`em`/`rem`/`ex`/`vw`/`vh` lengths · `font-size`, `font-family`,
+`line-height`, `letter-spacing`, `word-spacing` · `border-radius` (use
+`border: rounded`), `box-shadow`, `outline`, `filter`, `backdrop-filter` ·
+`transform` and friends · `background-image`, gradients · `float` ·
+`@font-face`, `@page`.

package/docs/selectors.md

@@ -0,0 +1,80 @@
+# Selectors and the cascade
+
+The selector engine implements standard
+[CSS selectors](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_selectors)
+with spec matching semantics, plus `::before`/`::after` generated
+content. Specificity, source order, and inline-`style` precedence follow
+the [cascade](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_cascade/Cascade);
+`inherit`, `initial`, and `unset` work.
+
+## Simple selectors and combinators
+
+- Type (`div`), class (`.card`), id (`#main`), universal (`*`), and
+  selector lists (`h1, h2`).
+- Combinators: descendant (`nav a`), child (`ul > li`), adjacent sibling
+  (`h2 + p`), general sibling (`h2 ~ p`).
+
+## Attribute selectors
+
+All operators, quoted or unquoted:
+
+| Form | Matches |
+|---|---|
+| `[disabled]` | attribute present |
+| `[type="text"]` | exact value |
+| `[href^="https"]` | prefix |
+| `[href$=".pdf"]` | suffix |
+| `[href*="docs"]` | substring |
+| `[data-tags~="beta"]` | whitespace-separated word |
+| `[lang\|="en"]` | exact or dash-prefixed (`en-GB`) |
+
+One renderer nuance: Svelte stringifies attribute values, so
+`disabled={false}` arrives as the string `"false"` — svelterm's boolean
+attribute handling (`:disabled`, `[open]` behaviours, focus skipping)
+treats `"false"` as off.
+
+## Pseudo-classes
+
+- **Structural:** `:root`, `:first-child`, `:last-child`, `:only-child`,
+  `:empty` (comments and empty text ignored, as in browsers),
+  `:first-of-type`, `:last-of-type`, `:only-of-type`, and the full An+B
+  family — `:nth-child()`, `:nth-last-child()`, `:nth-of-type()`,
+  `:nth-last-of-type()` (`odd`, `even`, `3`, `2n+1`, `-n+3`…).
+- **State:** `:focus` (keyboard/mouse focus), `:hover` (mouse),
+  `:checked`, `:disabled`, `:enabled` (form controls only, as in
+  browsers).
+- **Logical:** `:not()`, `:is()`, `:where()` (zero specificity), each
+  taking selector lists.
+
+```css
+tr:nth-child(even)        { background: #16181d; }
+input:checked             { color: green; }
+button:disabled           { opacity: dim; }
+details[open] > summary   { color: cyan; }
+```
+
+## Pseudo-elements: `::before` / `::after`
+
+Generated content renders as an inline box at the start/end of the
+element (legacy single-colon syntax accepted):
+
+```css
+a[href$=".pdf"]::after { content: " [pdf]"; color: red; }
+.badge::before         { content: attr(data-count) " "; font-weight: bold; }
+```
+
+`content:` supports quoted strings, `attr(x)` against the host element,
+space-separated concatenation, and `none`/`""` (no box). `counter()` is
+not supported. Pseudo boxes are invisible to `:empty` and `:nth-*`, and
+style like inline elements (they inherit the host's visual attributes
+unless the pseudo rule overrides them).
+
+Known gap: pseudo-elements don't render inside table-internal layout
+boxes.
+
+## What re-resolves when
+
+Selector matching is live: any attribute change (including inline
+`style`, `checked`, `open`, `data-*`) re-resolves the element and its
+descendants, so state-dependent rules like `details[open] > *` or
+`[data-status="error"]` update as your component mutates.

package/docs/terminal-css.md

@@ -0,0 +1,149 @@
+# Terminal CSS
+
+The terminal-specific surface: what svelterm adds to CSS, and how familiar
+properties map onto a character grid. Everything here is invalid or inert
+in browsers by design — the same stylesheet runs in both modes.
+
+## The `cell` unit
+
+One terminal cell is the atomic unit of layout:
+
+```css
+.sidebar { width: 24cell; padding: 1cell 2cell; }
+```
+
+- [`ch`](https://developer.mozilla.org/en-US/docs/Web/CSS/length#ch) is an
+  exact alias (`1ch` = `1cell`). Prefer `ch` in dual-target stylesheets —
+  browsers understand it too, and on a monospace grid it means the same
+  thing.
+- All lengths round to whole cells; `4.6cell` is 5.
+- Unitless `0` is valid, as in CSS. `%` is relative to the containing
+  block's cells. `fr` works in grid templates.
+- Pixel-derived units (`px`, `em`, `rem`, `vw`, `vh`…) parse and are
+  dropped — see [compatibility](./compatibility.md).
+
+## Targeting one mode
+
+svelterm evaluates `@media (display-mode: terminal)` as true; a
+`display-mode: browser` block is ignored by the terminal and applies in
+real browsers as plain CSS:
+
+```css
+.card {
+    @media (display-mode: browser)  { box-shadow: 0 2px 8px #0004; }
+    @media (display-mode: terminal) { border: single; }
+}
+```
+
+This is the documented pattern for everything svelterm deliberately
+ignores (shadows, radii, fonts, transforms).
+
+## Borders
+
+[`border-style`](https://developer.mozilla.org/en-US/docs/Web/CSS/border-style)
+takes terminal-native values drawn with box-drawing and block glyphs.
+Browser values (`solid`, `dashed`…) are ignored.
+
+| Value | Look |
+|---|---|
+| `single` | `┌─┐` light box drawing |
+| `double` | `╔═╗` double lines |
+| `rounded` | `╭─╮` rounded corners |
+| `heavy` | `┏━┓` heavy lines |
+| `ascii` | `+-+` plain ASCII |
+| `eighth-cell-inner` / `-outer` | thin eighth-block edges inside/outside the cell |
+| `half-cell-inner` / `-outer` | half-block edges |
+| `full-cell` | full-block frame |
+
+- Borders are exactly one cell thick and consume layout space.
+- Individual sides: `border-top: true` / `false` (setting one side first
+  disables the others).
+- `border-corner: h | v | none` biases which line wins at corners.
+- `border-color` is standard, including `currentColor`.
+- Tables support `border-collapse: collapse` with shared grid lines.
+
+```css
+.panel  { border: rounded; border-color: cyan; }
+.rule   { border-top: true; border-style: single; }  /* horizontal rule */
+```
+
+## Colour
+
+Resolved colours are ANSI palette names or 24-bit truecolor:
+
+- The 8 basic CSS keywords (`red`, `cyan`, …) map to ANSI palette names —
+  the user's terminal theme can restyle them.
+- Hex, `rgb()`, `hsl()`, `hwb()`, `lab()`, `lch()`, `oklab()`, `oklch()`
+  and the 148 named colours resolve to exact truecolor.
+- `transparent` means "no colour set": the parent's background shows
+  through. There is no alpha blending.
+- `currentColor` works wherever a colour is valid.
+
+### Dark/light schemes
+
+The terminal's own scheme is detected by polling OSC 11 (override with
+`run({ colorScheme })` or `setColorScheme()`). It drives both:
+
+```css
+:root { color-scheme: light dark; }
+.hint { color: light-dark(#64748b, #94a3b8); }
+@media (prefers-color-scheme: dark) { .logo { color: cyan; } }
+```
+
+[`light-dark()`](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value/light-dark)
+is usually the shortest way to theme a component for both schemes.
+
+## Alpha and opacity
+
+Terminals have no alpha layer, so svelterm composites at paint time:
+`rgba()`, `#rrggbbaa` and slash-alpha colours blend over whatever the
+cell already holds, and numeric `opacity` folds into the element's
+colours as a blend factor. Blending over ANSI colour names uses their
+nominal xterm values; blending over the terminal's *default* background
+assumes black — set an explicit background on an ancestor when
+compositing in light themes.
+
+```css
+.overlay { background: rgb(0 0 0 / 0.4); }   /* darkens what's beneath */
+.muted   { opacity: 0.6; }                    /* blends toward the bg */
+```
+
+The non-standard `opacity: dim` applies the terminal's *dim* attribute
+instead of blending. Animating `opacity` switches discretely — animate a
+colour toward the background for a smooth fade.
+
+## Text attributes
+
+`font-weight: bold`, `font-style: italic`, `text-decoration: underline`
+and `line-through` map to terminal attributes. `text-transform`,
+`text-align`, `white-space` (`normal`/`nowrap`/`pre`), `word-break`
+(`normal`/`break-all`), and `text-overflow: ellipsis` (plus non-standard
+`ellipsis-middle`, which keeps both ends of long paths) behave as
+standard. Font *choice* and *size* are the terminal emulator's business —
+`font-family`, `font-size`, `line-height` are ignored.
+
+Text is measured in **grapheme clusters and cell widths**: CJK and
+fullwidth characters occupy two cells, emoji (including ZWJ sequences)
+two, combining marks zero — so `1ch`-based layouts, wrapping, truncation
+and borders stay aligned with non-Latin content. Caveat: emoji width
+ultimately depends on the terminal's font; svelterm follows the modern
+two-cell convention.
+
+## `<svt-ansi>`
+
+Raw ANSI passthrough for pre-styled output — `git diff`, `ls --color`,
+build logs. Its text content renders with its own SGR styling (16/256/
+truecolor, bold, underline, …); non-SGR escape sequences are stripped.
+Content is treated as `pre`: newlines split lines, tabs expand to
+8-column stops, nothing wraps.
+
+```svelte
+<svt-ansi>{diffOutput}</svt-ansi>
+```
+
+## `<svt-region>`
+
+A paint primitive whose cells come from your code — used to embed whole
+terminal emulators (the playground's embedded-terminal demo). It fills its
+box like a replaced element, receives a cell-source callback, and fires
+`resize` with `{ cols, rows }` when its allocated size changes.