@svelterm/core 0.21.0 → 0.24.0

package/CHANGELOG.md

@@ -1,5 +1,64 @@
 # Changelog
 
+## 0.24.0 — 2026-07-05
+
+Motion timing completeness: transitions and keyframes behave per spec.
+
+### Added
+
+- **Per-property transitions** — `transition: color 150ms linear, width
+  400ms ease` runs each property on its own duration and timing;
+  longhand lists pair cyclically per spec. (Previously the first
+  duration and one timing function applied to everything.)
+- **Interrupted transitions continue** — a retargeted transition starts
+  from its current blended value instead of jumping back to the previous
+  target (reversals no longer flash).
+- **Per-keyframe `animation-timing-function`** — a timing function
+  declared inside a keyframe applies from that stop to the next.
+- **Keyframe `var()`/`light-dark()` re-resolution** — scheme flips and
+  custom-property changes retarget a running animation in place, without
+  restarting it.
+
+## 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/animation-runner.d.ts

@@ -1,6 +1,6 @@
 import type { KeyframeStop } from './parser.js';
 import { type ResolvedStyle } from './compute.js';
-import type { Easing } from './easing.js';
+import { type Easing } from './easing.js';
 /**
  * Runs a CSS animation by applying keyframe properties at the current
  * time. Colours interpolate in RGB space between stops; properties that

package/dist/src/css/animation-runner.js

@@ -1,5 +1,6 @@
 import { applyDeclaration } from './compute.js';
 import { resolveColor } from './color.js';
+import { parseEasing } from './easing.js';
 import { lerpColor, lerpNumber } from './interpolate.js';
 import { parseCellLength } from './values.js';
 /** Properties whose animation only needs repaint; anything else re-layouts. */
@@ -37,7 +38,11 @@ export class AnimationRunner {
         const progress = this.getProgress(elapsedMs);
         const segment = this.segmentAt(progress);
         const { from, to } = segment;
-        const localT = this.easing(segment.localT);
+        // A timing function declared inside a keyframe applies from that
+        // stop to the next, overriding the element-level easing (per CSS).
+        const override = from.declarations.find(d => d.property === 'animation-timing-function');
+        const easing = override ? (parseEasing(override.value) ?? this.easing) : this.easing;
+        const localT = easing(segment.localT);
         // Hold the earlier stop's values, then interpolate toward the next
         for (const decl of from.declarations) {
             applyAnimatedProperty(style, decl);
@@ -87,6 +92,9 @@ export class AnimationRunner {
     }
 }
 function applyAnimatedProperty(style, decl) {
+    // Keyframe-level timing functions steer the runner, not the style
+    if (decl.property === 'animation-timing-function')
+        return;
     applyDeclaration(style, decl.property, decl.value);
 }
 function applyInterpolatedProperty(style, from, to, t) {

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

@@ -53,6 +53,15 @@ export interface ResolvedStyle {
     transitionProperty: string | null;
     transitionDuration: number;
     transitionTimingFunction: string;
+    /** Longhand lists, paired cyclically per spec into `transitions`. */
+    transitionDurations: number[];
+    transitionTimings: string[];
+    /** Per-property transition config, resolved after cascade. */
+    transitions: Array<{
+        property: string;
+        duration: number;
+        timing: string;
+    }>;
     borderStyle: 'none' | 'single' | 'double' | 'rounded' | 'heavy' | 'ascii' | 'eighth-cell-inner' | 'eighth-cell-outer' | 'half-cell-inner' | 'half-cell-outer' | 'full-cell';
     borderCorner: 'none' | 'h' | 'v';
     borderColor: string;
@@ -68,7 +77,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;
@@ -88,3 +97,12 @@ export declare function resolveStyles(root: TermNode, stylesheet: CSSStyleSheet,
 export declare function filterByMedia(stylesheet: CSSStyleSheet, context: MediaContext): CSSStyleSheet;
 export declare function resolveNode(node: TermNode, stylesheet: CSSStyleSheet, styles: Map<number, ResolvedStyle>, variables: Map<number, Map<string, string>>, scheme?: 'dark' | 'light'): void;
 export declare function applyDeclaration(style: ResolvedStyle, property: string, value: string, scheme?: 'dark' | 'light'): void;
+/**
+ * Pair the transition lists per spec: durations/timings repeat
+ * cyclically to cover every listed property.
+ */
+export declare function pairTransitions(style: ResolvedStyle): Array<{
+    property: string;
+    duration: number;
+    timing: string;
+}>;

package/dist/src/css/compute.js

@@ -56,6 +56,8 @@ export function defaultStyle(tag) {
         animationTimingFunction: 'ease',
         transitionProperty: null, transitionDuration: 0,
         transitionTimingFunction: 'ease',
+        transitionDurations: [], transitionTimings: [],
+        transitions: [],
         borderStyle: 'none', borderColor: 'default', borderCorner: 'none',
         borderTop: true, borderRight: true, borderBottom: true, borderLeft: true,
         boxSizing: 'border-box',
@@ -272,6 +274,8 @@ function computeStyle(node, stylesheet, vars, parentStyle, scheme = 'dark') {
             applyDeclaration(style, decl.property, resolveVar(decl.value, vars), scheme);
         }
     }
+    // Pair transition longhand lists now the cascade is complete
+    style.transitions = pairTransitions(style);
     return style;
 }
 function parseInlineStyle(text) {
@@ -563,10 +567,12 @@ export function applyDeclaration(style, property, value, scheme = 'dark') {
             style.transitionProperty = value === 'none' ? null : value;
             break;
         case 'transition-duration':
-            style.transitionDuration = parseDuration(value);
+            style.transitionDurations = value.split(',').map(v => parseDuration(v.trim()));
+            style.transitionDuration = style.transitionDurations[0] ?? 0;
             break;
         case 'transition-timing-function':
-            style.transitionTimingFunction = value;
+            style.transitionTimings = splitTimingList(value);
+            style.transitionTimingFunction = style.transitionTimings[0] ?? 'ease';
             break;
         case 'animation-name':
             style.animationName = value === 'none' ? null : value;
@@ -639,7 +645,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';
@@ -806,35 +812,85 @@ function parseAnimationShorthand(style, value) {
         }
     }
 }
-/** Parse `transition: <property> <duration> [...]`, comma-separated groups. */
+/** Split a timing-function list on commas, keeping function args intact. */
+function splitTimingList(value) {
+    const out = [];
+    let depth = 0;
+    let current = '';
+    for (const ch of value) {
+        if (ch === '(')
+            depth++;
+        if (ch === ')')
+            depth--;
+        if (ch === ',' && depth === 0) {
+            out.push(current.trim());
+            current = '';
+        }
+        else
+            current += ch;
+    }
+    if (current.trim())
+        out.push(current.trim());
+    return out;
+}
+/**
+ * Parse `transition: <property> <duration> <timing> [...]` — each
+ * comma-separated group configures one property (or `all`).
+ */
 function parseTransitionShorthand(style, value) {
     const trimmed = value.trim();
     if (trimmed === 'none') {
         style.transitionProperty = null;
         style.transitionDuration = 0;
+        style.transitionDurations = [];
+        style.transitionTimings = [];
         return;
     }
-    const { easing, rest } = extractEasingFunction(trimmed);
-    if (easing)
-        style.transitionTimingFunction = easing;
     const properties = [];
-    let duration = 0;
-    for (const group of rest.split(',')) {
-        for (const token of group.trim().split(/\s+/)) {
+    const durations = [];
+    const timings = [];
+    for (const groupRaw of splitTimingList(trimmed)) {
+        const { easing, rest } = extractEasingFunction(groupRaw);
+        let property = 'all';
+        let duration = 0;
+        let timing = easing ?? 'ease';
+        for (const token of rest.trim().split(/\s+/)) {
             if (/^\d*\.?\d+(ms|s)$/.test(token)) {
                 if (duration === 0)
                     duration = parseDuration(token);
             }
             else if (TIMING_KEYWORDS.has(token)) {
-                style.transitionTimingFunction = token;
+                timing = token;
             }
             else if (token) {
-                properties.push(token);
+                property = token;
             }
         }
+        properties.push(property);
+        durations.push(duration);
+        timings.push(timing);
     }
     style.transitionProperty = properties.length > 0 ? properties.join(',') : 'all';
-    style.transitionDuration = duration;
+    style.transitionDurations = durations;
+    style.transitionTimings = timings;
+    style.transitionDuration = durations[0] ?? 0;
+    style.transitionTimingFunction = timings[0] ?? 'ease';
+}
+/**
+ * Pair the transition lists per spec: durations/timings repeat
+ * cyclically to cover every listed property.
+ */
+export function pairTransitions(style) {
+    if (!style.transitionProperty)
+        return [];
+    const properties = style.transitionProperty.split(',').map(p => p.trim()).filter(Boolean);
+    const durations = style.transitionDurations.length > 0 ? style.transitionDurations : [style.transitionDuration];
+    const timings = style.transitionTimings.length > 0 ? style.transitionTimings : [style.transitionTimingFunction];
+    return properties.map((property, i) => ({
+        property,
+        duration: durations[i % durations.length] ?? 0,
+        timing: timings[i % timings.length] ?? 'ease',
+    }));
 }
 function parseDuration(value) {
     if (value.endsWith('ms'))

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,20 @@ export type { KeyframeResolution } from '../css/animation.js';
  * wires `onFrame` to re-apply and repaint.
  */
 export declare class AnimationClock {
-    private now;
     private active;
+    /** Per-property transition runners, keyed `nodeId:property`. */
     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;
@@ -45,7 +52,14 @@ export declare class AnimationClock {
     stop(): void;
     private discover;
     private discoverTransitions;
-    /** Snapshot the node's target values; start a transition on any change. */
+    /**
+     * Snapshot the node's target values; start a per-property transition
+     * runner on any change, each with its own duration and timing. An
+     * interrupted transition continues from its current blended value
+     * rather than restarting from the previous target.
+     */
     private trackTransitionTargets;
+    /** Evaluate an in-flight transition's value for one property, now. */
+    private currentValue;
     private updateTimer;
 }

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

@@ -1,21 +1,11 @@
 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);
 }
-/** Parse a transition-property value into the tracked-property filter. */
-function transitionedProperties(value) {
-    const names = new Set();
-    for (const raw of value.split(',')) {
-        const name = raw.trim();
-        if (name === 'all')
-            return { all: true, names };
-        names.add(name === 'background' ? 'background-color' : name);
-    }
-    return { all: false, names };
-}
 function cellValue(value) {
     return typeof value === 'number' && value >= 0 ? `${value}cell` : null;
 }
@@ -48,23 +38,36 @@ const FRAME_INTERVAL_MS = 33;
  * wires `onFrame` to re-apply and repaint.
  */
 export class AnimationClock {
-    now;
     active = new Map();
+    /** Per-property transition runners, keyed `nodeId:property`. */
     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;
     }
     /** Whether this node's animation needs re-layout each frame (vs repaint only). */
     touchesLayout(node) {
-        return (this.active.get(node.id)?.runner.touchesLayout
-            || this.transitions.get(node.id)?.runner.touchesLayout) ?? false;
+        if (this.active.get(node.id)?.runner.touchesLayout)
+            return true;
+        for (const anim of this.transitions.values()) {
+            if (anim.node.id === node.id && anim.runner.touchesLayout)
+                return true;
+        }
+        return false;
     }
     /**
      * Track transitioned elements and start a one-shot transition when a
@@ -79,7 +82,10 @@ export class AnimationClock {
         for (const id of this.transitionTargets.keys()) {
             if (!seen.has(id)) {
                 this.transitionTargets.delete(id);
-                this.transitions.delete(id);
+                for (const key of this.transitions.keys()) {
+                    if (key.startsWith(`${id}:`))
+                        this.transitions.delete(key);
+                }
             }
         }
         this.updateTimer();
@@ -108,20 +114,20 @@ export class AnimationClock {
         return dirty;
     }
     applyEntries(entries, styles, dirty) {
-        for (const [id, anim] of entries) {
-            const style = styles.get(id);
+        for (const [key, anim] of entries) {
+            const style = styles.get(anim.node.id);
             if (!style)
                 continue;
             const elapsed = this.now() - anim.start;
             anim.runner.apply(style, elapsed);
             dirty.push({ node: anim.node, touchesLayout: anim.runner.touchesLayout });
             if (anim.runner.isFinished(elapsed))
-                entries.delete(id);
+                entries.delete(key);
         }
     }
     stop() {
         if (this.timer !== null) {
-            clearInterval(this.timer);
+            this.clock.clearInterval(this.timer);
             this.timer = null;
         }
     }
@@ -132,18 +138,27 @@ export class AnimationClock {
             const stops = name ? keyframes.get(name) : undefined;
             if (style && name && stops && style.animationDuration > 0) {
                 const existing = this.active.get(node.id);
+                const resolved = resolution
+                    ? resolveKeyframeStops(stops, resolution, node.id)
+                    : stops;
+                const resolvedKey = JSON.stringify(resolved);
                 if (!existing || existing.name !== name || existing.duration !== style.animationDuration) {
-                    const resolved = resolution
-                        ? resolveKeyframeStops(stops, resolution, node.id)
-                        : stops;
                     this.active.set(node.id, {
                         node,
                         runner: new AnimationRunner(resolved, style.animationDuration, style.animationIterationCount, easingFor(style.animationTimingFunction)),
                         name,
                         duration: style.animationDuration,
                         start: this.now(),
+                        resolvedKey,
                     });
                 }
+                else if (existing.resolvedKey !== undefined && existing.resolvedKey !== resolvedKey) {
+                    // var()/light-dark() re-resolved to new values (scheme
+                    // flip, custom property change): retarget the runner
+                    // without restarting — the original start time holds.
+                    existing.runner = new AnimationRunner(resolved, style.animationDuration, style.animationIterationCount, easingFor(style.animationTimingFunction));
+                    existing.resolvedKey = resolvedKey;
+                }
                 seen.add(node.id);
             }
         }
@@ -154,7 +169,7 @@ export class AnimationClock {
         const subtreeResolved = parentResolved || (resolvedIds?.has(node.id) ?? false);
         if (node.nodeType === 'element') {
             const style = styles.get(node.id);
-            if (style?.transitionProperty && style.transitionDuration > 0) {
+            if (style && style.transitions.some(t => t.duration > 0)) {
                 seen.add(node.id);
                 if (subtreeResolved)
                     this.trackTransitionTargets(node, style);
@@ -164,12 +179,20 @@ export class AnimationClock {
             this.discoverTransitions(child, styles, subtreeResolved, resolvedIds, seen);
         }
     }
-    /** Snapshot the node's target values; start a transition on any change. */
+    /**
+     * Snapshot the node's target values; start a per-property transition
+     * runner on any change, each with its own duration and timing. An
+     * interrupted transition continues from its current blended value
+     * rather than restarting from the previous target.
+     */
     trackTransitionTargets(node, style) {
-        const included = transitionedProperties(style.transitionProperty);
+        const configFor = (css) => style.transitions.find(t => t.property === css
+            || (t.property === 'background' && css === 'background-color'))
+            ?? style.transitions.find(t => t.property === 'all');
         const targets = {};
         for (const prop of TRANSITIONABLE) {
-            if (!included.all && !included.names.has(prop.css))
+            const config = configFor(prop.css);
+            if (!config || config.duration <= 0)
                 continue;
             const value = prop.read(style);
             if (value !== null)
@@ -179,32 +202,42 @@ export class AnimationClock {
         this.transitionTargets.set(node.id, targets);
         if (!previous)
             return; // first sight — the initial style never transitions
-        const fromDecls = [];
-        const toDecls = [];
         for (const [property, target] of Object.entries(targets)) {
             const before = previous[property];
-            if (before !== undefined && before !== target) {
-                fromDecls.push({ property, value: before });
-                toDecls.push({ property, value: target });
+            if (before === undefined || before === target)
+                continue;
+            const config = configFor(property);
+            const key = `${node.id}:${property}`;
+            // Interrupted mid-flight? Continue from the current value.
+            let from = before;
+            const inFlight = this.transitions.get(key);
+            if (inFlight) {
+                const current = this.currentValue(inFlight, style, property);
+                if (current !== null)
+                    from = current;
             }
+            const stops = [
+                { offset: 0, declarations: [{ property, value: from }] },
+                { offset: 1, declarations: [{ property, value: target }] },
+            ];
+            this.transitions.set(key, {
+                node,
+                runner: new AnimationRunner(stops, config.duration, 1, easingFor(config.timing)),
+                name: property,
+                duration: config.duration,
+                start: this.now(),
+            });
         }
-        if (fromDecls.length === 0)
-            return;
-        const stops = [
-            { offset: 0, declarations: fromDecls },
-            { offset: 1, declarations: toDecls },
-        ];
-        this.transitions.set(node.id, {
-            node,
-            runner: new AnimationRunner(stops, style.transitionDuration, 1, easingFor(style.transitionTimingFunction)),
-            name: '',
-            duration: style.transitionDuration,
-            start: this.now(),
-        });
+    }
+    /** Evaluate an in-flight transition's value for one property, now. */
+    currentValue(anim, base, property) {
+        const scratch = { ...base };
+        anim.runner.apply(scratch, this.now() - anim.start);
+        return TRANSITIONABLE.find(p => p.css === property)?.read(scratch) ?? null;
     }
     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/motion.md

@@ -66,19 +66,20 @@ inline style updates, a `:checked` rule starts applying:
 `ms`/`s`. The same interpolation rules as animations apply. The initial
 style never transitions.
 
+Transitions are configured per property, per spec: comma-separated
+shorthand groups (`transition: color 150ms linear, width 400ms ease`)
+or longhand lists paired cyclically. An interrupted transition
+continues from its current blended value. A timing function declared
+*inside a keyframe* applies from that stop to the next, overriding the
+element's. Keyframe `var()`/`light-dark()` values re-resolve when the
+scheme or custom properties change mid-animation, retargeting without
+restarting.
+
 ## 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.
+- `transition-delay` / `animation-delay` are not implemented.
 
 ## Reduced motion
 

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,11 +172,11 @@ 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()`) |
-| [Transitions](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_transitions) | `transition` shorthand, `transition-property` (list or `all`), `transition-duration`, `transition-timing-function` |
+| [Transitions](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_transitions) | `transition` shorthand with per-property comma groups; `transition-property`/`-duration`/`-timing-function` longhand lists paired per spec; interruptions continue from the current value |
 | [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
@@ -184,12 +185,14 @@ 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.
+each frame. Easing applies per keyframe segment (a timing function
+declared inside a keyframe overrides the element's for that segment);
+non-interpolable values switch when eased progress crosses the midpoint.
+Transitions run per property with their own duration/timing;
+interruptions continue from the current blended value. Keyframe
+`var()`/`light-dark()` re-resolves on scheme/custom-property changes
+without restarting the animation. Deviation: no `transition-delay` /
+`animation-delay`.
 
 ## Values, functions and at-rules
 

package/package.json

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