@svelterm/core 0.21.0 → 0.23.0

package/CHANGELOG.md

@@ -1,5 +1,45 @@
 # Changelog
 
+## 0.23.0 — 2026-07-05
+
+Positioning: `relative` offsets apply, and `sticky` arrives.
+
+### Added
+
+- **`position: relative`** — `top/right/bottom/left` now shift the box
+  and its descendants visually while flow position and size behave as if
+  unshifted, per spec (previously parsed and dropped).
+- **`position: sticky`** (top edge) — inside a scroll container the
+  element pins to the container top + `top` once scrolled past, painting
+  above in-flow content; descendants move with it. Deviations
+  (documented): top-only, no push-out at the containing-block end, and
+  hit-testing targets the flow position.
+
+### Fixed
+
+- **Opaque backgrounds now cover what's beneath** — an element's
+  background fill previously kept stale glyphs from earlier paints, so
+  overlapping paints (sticky, absolute) showed old content through the
+  background. Fills now clear covered cells.
+
+## 0.22.0 — 2026-07-05
+
+### Added
+
+- **`Clock` seam for deterministic animation tests** — the animation
+  engine's time source *and* its frame scheduler now go through a
+  `Clock` interface. `TestClock` (exported) lets tests set time and
+  advance it, firing the frame timer at each tick — so the animation and
+  transition frame lifecycle is exact, not `setInterval`/`Date.now`
+  dependent. `run()` uses the real `systemClock` by default.
+
+### Fixed
+
+- **Docs: `<img>` rendering** — `reference.md` still listed `img` as
+  "not rendered", and `elements.md`'s intro contradicted its own Images
+  section. Both now describe the half-block + kitty-graphics rendering
+  shipped in 0.15.0 / 0.19.0.
+
 ## 0.21.0 — 2026-07-05
 
 DevTools polish.

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

@@ -68,7 +68,7 @@ export interface ResolvedStyle {
     opacity: number;
     textAlign: 'left' | 'center' | 'right';
     textTransform: 'none' | 'uppercase' | 'lowercase' | 'capitalize';
-    position: 'static' | 'relative' | 'absolute' | 'fixed';
+    position: 'static' | 'relative' | 'absolute' | 'fixed' | 'sticky';
     top: number | null;
     right: number | null;
     bottom: number | null;

package/dist/src/css/compute.js

@@ -639,7 +639,7 @@ export function applyDeclaration(style, property, value, scheme = 'dark') {
                 style.textTransform = 'none';
             break;
         case 'position':
-            if (value === 'relative' || value === 'absolute' || value === 'fixed')
+            if (value === 'relative' || value === 'absolute' || value === 'fixed' || value === 'sticky')
                 style.position = value;
             else
                 style.position = 'static';

package/dist/src/index.d.ts

@@ -78,3 +78,4 @@ export { StdinRouter } from './terminal/stdin-router.js';
 export { type TerminalIO, ProcessIO, InProcessIO } from './terminal/io.js';
 export { copyToClipboard, osc52Copy } from './terminal/clipboard.js';
 export { FrameLog, createFrameLog } from './framelog.js';
+export { type Clock, TestClock, systemClock } from './render/clock.js';

package/dist/src/index.js

@@ -1011,3 +1011,4 @@ export { StdinRouter } from './terminal/stdin-router.js';
 export { ProcessIO, InProcessIO } from './terminal/io.js';
 export { copyToClipboard, osc52Copy } from './terminal/clipboard.js';
 export { FrameLog, createFrameLog } from './framelog.js';
+export { TestClock, systemClock } from './render/clock.js';

package/dist/src/layout/engine.js

@@ -159,6 +159,14 @@ function layoutElement(node, styles, boxes, x, y, availWidth, availHeight) {
         const absY = y + (style.top ?? 0);
         return layoutAbsolute(node, styles, boxes, absX, absY, availWidth, availHeight, style);
     }
+    // position: relative — a visual shift of the box and its descendants;
+    // flow position and size behave as if unshifted (the return value,
+    // which advances the flow, is untouched). left beats right, top beats
+    // bottom, per LTR CSS.
+    if (style?.position === 'relative') {
+        x += style.left ?? -(style.right ?? 0);
+        y += style.top ?? -(style.bottom ?? 0);
+    }
     let margin = {
         top: resolvePadding(style?.marginTop, availWidth),
         right: resolvePadding(style?.marginRight, availWidth),

package/dist/src/render/animation-clock.d.ts

@@ -2,6 +2,7 @@ import { TermNode } from '../renderer/node.js';
 import { type KeyframeResolution } from '../css/animation.js';
 import type { KeyframeStop } from '../css/parser.js';
 import type { ResolvedStyle } from '../css/compute.js';
+import { type Clock } from './clock.js';
 export type { KeyframeResolution } from '../css/animation.js';
 /**
  * Drives CSS animations: discovers animated elements after style
@@ -10,14 +11,19 @@ export type { KeyframeResolution } from '../css/animation.js';
  * wires `onFrame` to re-apply and repaint.
  */
 export declare class AnimationClock {
-    private now;
     private active;
     private transitions;
     /** Last-seen target values per transitioned node, as CSS property → value. */
     private transitionTargets;
     private timer;
+    private clock;
     onFrame?: () => void;
-    constructor(now?: () => number);
+    /**
+     * Accepts a Clock (time source + scheduler) or, for convenience and
+     * backward compatibility, a bare `() => number` time function.
+     */
+    constructor(clock?: Clock | (() => number));
+    private now;
     get activeCount(): number;
     /** Whether this node's animation needs re-layout each frame (vs repaint only). */
     touchesLayout(node: TermNode): boolean;

package/dist/src/render/animation-clock.js

@@ -1,6 +1,7 @@
 import { AnimationRunner } from '../css/animation-runner.js';
 import { resolveKeyframeStops } from '../css/animation.js';
 import { parseEasing } from '../css/easing.js';
+import { systemClock, clockFromNow } from './clock.js';
 /** The runner's easing for a CSS timing-function value; invalid → linear. */
 function easingFor(value) {
     return parseEasing(value) ?? (t => t);
@@ -48,15 +49,22 @@ const FRAME_INTERVAL_MS = 33;
  * wires `onFrame` to re-apply and repaint.
  */
 export class AnimationClock {
-    now;
     active = new Map();
     transitions = new Map();
     /** Last-seen target values per transitioned node, as CSS property → value. */
     transitionTargets = new Map();
     timer = null;
+    clock;
     onFrame;
-    constructor(now = Date.now) {
-        this.now = now;
+    /**
+     * Accepts a Clock (time source + scheduler) or, for convenience and
+     * backward compatibility, a bare `() => number` time function.
+     */
+    constructor(clock = systemClock) {
+        this.clock = typeof clock === 'function' ? clockFromNow(clock) : clock;
+    }
+    now() {
+        return this.clock.now();
     }
     get activeCount() {
         return this.active.size + this.transitions.size;
@@ -121,7 +129,7 @@ export class AnimationClock {
     }
     stop() {
         if (this.timer !== null) {
-            clearInterval(this.timer);
+            this.clock.clearInterval(this.timer);
             this.timer = null;
         }
     }
@@ -204,7 +212,7 @@ export class AnimationClock {
     }
     updateTimer() {
         if (this.activeCount > 0 && this.timer === null) {
-            this.timer = setInterval(() => this.onFrame?.(), FRAME_INTERVAL_MS);
+            this.timer = this.clock.setInterval(() => this.onFrame?.(), FRAME_INTERVAL_MS);
         }
         else if (this.activeCount === 0) {
             this.stop();

package/dist/src/render/clock.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Clock seam for time-driven rendering (animations, transitions, and the
+ * scrollbar fade). Abstracts both the time source and the frame
+ * scheduler so tests can advance time and fire ticks deterministically
+ * instead of depending on `Date.now()` and real `setInterval`.
+ */
+export type ClockTimer = unknown;
+export interface Clock {
+    now(): number;
+    setInterval(fn: () => void, ms: number): ClockTimer;
+    clearInterval(timer: ClockTimer): void;
+}
+/** The real clock: wall time and the platform timer. */
+export declare const systemClock: Clock;
+/** Wrap a bare time function in a Clock backed by the real scheduler. */
+export declare function clockFromNow(now: () => number): Clock;
+/**
+ * A controllable clock for tests: set the time directly, or `advance`
+ * it, which fires any registered intervals at each tick they cross.
+ */
+export declare class TestClock implements Clock {
+    private time;
+    private timers;
+    constructor(start?: number);
+    now(): number;
+    setInterval(fn: () => void, ms: number): ClockTimer;
+    clearInterval(timer: ClockTimer): void;
+    /** Jump to an absolute time without firing intervals. */
+    setTime(time: number): void;
+    /** Advance by `ms`, firing each interval at every tick it crosses. */
+    advance(ms: number): void;
+    /** Timers registered right now (for assertions). */
+    get activeTimers(): number;
+    private nextTimerBefore;
+}

package/dist/src/render/clock.js

@@ -0,0 +1,67 @@
+/**
+ * Clock seam for time-driven rendering (animations, transitions, and the
+ * scrollbar fade). Abstracts both the time source and the frame
+ * scheduler so tests can advance time and fire ticks deterministically
+ * instead of depending on `Date.now()` and real `setInterval`.
+ */
+/** The real clock: wall time and the platform timer. */
+export const systemClock = {
+    now: () => Date.now(),
+    setInterval: (fn, ms) => setInterval(fn, ms),
+    clearInterval: (timer) => clearInterval(timer),
+};
+/** Wrap a bare time function in a Clock backed by the real scheduler. */
+export function clockFromNow(now) {
+    return { now, setInterval: systemClock.setInterval, clearInterval: systemClock.clearInterval };
+}
+/**
+ * A controllable clock for tests: set the time directly, or `advance`
+ * it, which fires any registered intervals at each tick they cross.
+ */
+export class TestClock {
+    time;
+    timers = new Set();
+    constructor(start = 0) {
+        this.time = start;
+    }
+    now() {
+        return this.time;
+    }
+    setInterval(fn, ms) {
+        const timer = { fn, ms, next: this.time + ms };
+        this.timers.add(timer);
+        return timer;
+    }
+    clearInterval(timer) {
+        this.timers.delete(timer);
+    }
+    /** Jump to an absolute time without firing intervals. */
+    setTime(time) {
+        this.time = time;
+    }
+    /** Advance by `ms`, firing each interval at every tick it crosses. */
+    advance(ms) {
+        const target = this.time + ms;
+        while (true) {
+            const due = this.nextTimerBefore(target);
+            if (!due)
+                break;
+            this.time = due.next;
+            due.next += due.ms;
+            due.fn();
+        }
+        this.time = target;
+    }
+    /** Timers registered right now (for assertions). */
+    get activeTimers() {
+        return this.timers.size;
+    }
+    nextTimerBefore(target) {
+        let earliest = null;
+        for (const timer of this.timers) {
+            if (timer.next <= target && (!earliest || timer.next < earliest.next))
+                earliest = timer;
+        }
+        return earliest;
+    }
+}

package/dist/src/render/paint.js

@@ -25,7 +25,21 @@ function paintNode(node, buffer, styles, layout, inherited, clip, scroll, damage
         return;
     const visuals = resolveVisuals(node, styles, inherited);
     const rawBox = layout?.get(node.id);
-    const box = rawBox ? applyScroll(rawBox, scroll) : undefined;
+    let box = rawBox ? applyScroll(rawBox, scroll) : undefined;
+    // position: sticky (top): when scrolled past inside a clipping
+    // container, pin to the container top + offset. Descendants follow
+    // via an adjusted child scroll; applied before culling so a stuck
+    // element scrolled far past its flow position still paints.
+    let stickyDelta = 0;
+    if (box && clip && node.nodeType === 'element') {
+        const stickyStyle = styles?.get(node.id);
+        if (stickyStyle?.position === 'sticky' && stickyStyle.top !== null) {
+            const stuckY = Math.max(box.y, clip.y + (stickyStyle.top ?? 0));
+            stickyDelta = stuckY - box.y;
+            if (stickyDelta > 0)
+                box = { ...box, y: stuckY };
+        }
+    }
     // Skip nodes entirely outside the damage region
     if (damageClip && box && !boxesOverlap(box, damageClip))
         return;
@@ -118,7 +132,18 @@ function paintNode(node, buffer, styles, layout, inherited, clip, scroll, damage
             childScroll = { x: scroll.x + node.scrollLeft, y: scroll.y + node.scrollTop };
         }
     }
-    for (const child of childrenWithPseudos(node)) {
+    // Descendants of a stuck element move with it
+    if (stickyDelta > 0)
+        childScroll = { x: childScroll.x, y: childScroll.y - stickyDelta };
+    // Sticky children paint after in-flow siblings so scrolled content
+    // doesn't overpaint a stuck header (positioned elements stack above).
+    const kids = childrenWithPseudos(node);
+    const hasSticky = kids.some(c => c.nodeType === 'element' && styles?.get(c.id)?.position === 'sticky');
+    const ordered = hasSticky
+        ? [...kids.filter(c => styles?.get(c.id)?.position !== 'sticky'),
+            ...kids.filter(c => styles?.get(c.id)?.position === 'sticky')]
+        : kids;
+    for (const child of ordered) {
         paintNode(child, buffer, styles, layout, visuals, childClip, childScroll, damageClip);
     }
     // Render scrollbar overlays for scrollable containers
@@ -233,7 +258,11 @@ function fillBackground(buffer, box, visuals, clip, style) {
             const bg = bgHasAlpha
                 ? blendColor(buffer.getCell(col, row)?.bg ?? 'default', visuals.bg)
                 : visuals.bg;
-            buffer.setCell(col, row, { bg });
+            // An opaque fill covers what's beneath — clear stale glyphs
+            // too, so overlapping paints (sticky, absolute) don't show
+            // earlier content through the background. The element's own
+            // text repaints after this fill.
+            buffer.setCell(col, row, { bg, char: ' ' });
         }
     }
 }

package/docs/elements.md

@@ -9,9 +9,9 @@ its display default.
 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).
+`samp`, `var`) carry a browser-like UA stylesheet in cells. `img`
+renders (see [Images](#images) below); `video`, `canvas`, and `iframe`
+are not rendered.
 
 ## Images
 

package/docs/layout.md

@@ -92,8 +92,14 @@ cells has no baseline distinct from its top).
 
 `position: absolute` and `fixed` take elements out of flow and place them
 by `top`/`right`/`bottom`/`left` with `z-index` stacking. `position:
-relative` establishes context but **offsets are not applied** — a known
-gap. Sub-cell geometry (`transform`, floats) is out of scope; see
+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

package/docs/reference.md

@@ -137,7 +137,8 @@ block/inline box per its display default.
 | `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`, `video`, `canvas`, `iframe` | **not rendered** (inline images are a planned separate feature) | — |
+| `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
 
@@ -171,7 +172,7 @@ adaptations. Lengths are cells (`cell`/`ch`, `%`, or `calc()`).
 | [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/absolute/fixed` with `top/right/bottom/left`, `z-index`. `position: relative` establishes context but offsets are **not** applied |
+| [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()`) |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@svelterm/core",
-  "version": "0.21.0",
+  "version": "0.23.0",
   "description": "Svelte 5 components rendered to the terminal with real CSS",
   "type": "module",
   "exports": {