@svelterm/core 0.1.0 → 0.23.0

package/dist/src/index.js

@@ -1,10 +1,16 @@
+import { mount, unmount } from 'svelte/renderer';
 import { TermNode } from './renderer/index.js';
+import { hasBooleanAttribute } from './renderer/node.js';
+import { AnimationClock } from './render/animation-clock.js';
+import { getKeyframes } from './css/animation.js';
 import renderer from './renderer/default.js';
 import { CellBuffer } from './render/buffer.js';
 import { diffBuffers } from './render/diff.js';
 import { paint } from './render/paint.js';
 import { parseCSS } from './css/parser.js';
+import { DEFAULT_STYLESHEET } from './css/defaults.js';
 import { resolveStyles, filterByMedia } from './css/compute.js';
+import { collectVariables } from './css/variables.js';
 import { resolveStylesIncremental } from './css/incremental.js';
 import { computeLayout } from './layout/engine.js';
 import { computeLayoutIncremental } from './layout/incremental.js';
@@ -16,33 +22,159 @@ import { parseMouseEvent } from './input/mouse.js';
 import { hitTest } from './input/hit.js';
 import { FocusManager } from './input/focus.js';
 import { dispatchEvent } from './input/dispatch.js';
+import { isCheckableInput, toggleCheckable } from './input/checkable.js';
+import { toggleDetails } from './input/details.js';
+import { cycleSelect } from './input/select.js';
+import { labelledControl } from './input/label.js';
 import { TextBuffer } from './components/text-buffer.js';
 import { StdinRouter, matchOSC11, parseOSC11Scheme } from './terminal/stdin-router.js';
-import { DebugServer } from './debug/server.js';
-import { ConsoleDomain } from './debug/console.js';
+import { detectCapabilities, matchCPR, parseCPRRow } from './terminal/capabilities.js';
+import { copyToClipboard } from './terminal/clipboard.js';
+import { SelectionController, applySelectionOverlay } from './input/selection.js';
+import { InlineScreen } from './render/inline.js';
+import { GraphicsLayer } from './render/graphics-layer.js';
+import { registerInlineHooks } from './framelog.js';
+import { activeModal, withinSubtree } from './input/modal.js';
 import * as ansi from './render/ansi.js';
-import { getTerminalSize, enterFullscreen, exitFullscreen, enableRawMode, disableRawMode, writeOutput, } from './terminal/screen.js';
+import { emitFocusCursor } from './render/cursor-emit.js';
+import { enterFullscreen, exitFullscreen } from './terminal/screen.js';
+import { ProcessIO } from './terminal/io.js';
+/** Deduped so HMR re-evaluation doesn't accumulate copies. */
+const registeredComponentCss = new Set();
+/**
+ * Register a component's extracted CSS before run() is called. Bundled
+ * builds (`svelterm build`) and the dev-mode transform append a
+ * registration call to each compiled component so it carries its styles;
+ * run() falls back to the registry when no `css` option is given.
+ */
+export function registerComponentCss(css) {
+    if (css)
+        registeredComponentCss.add(css);
+}
 export function run(AppComponent, options) {
-    const fullscreen = options?.fullscreen ?? true;
+    const io = options?.io ?? new ProcessIO();
+    // `fullscreen: false` without an explicit mode gets the inline
+    // renderer (what a main-buffer app actually needs). An explicit
+    // `mode` always wins — `mode: 'fullscreen', fullscreen: false` is
+    // full-viewport rendering without the alternate screen (embedded
+    // previews drive a virtual terminal that way).
+    const inline = options?.mode ? options.mode === 'inline' : options?.fullscreen === false;
+    const fullscreen = !inline && (options?.fullscreen ?? true);
     const mouseEnabled = options?.mouse ?? true;
     const debugEnabled = options?.debug ?? false;
     const debugPort = options?.debugPort ?? 9444;
-    const stylesheet = options?.css ? parseCSS(options.css) : null;
+    const exitOn = options?.exitOn ?? ['ctrl+c'];
+    const userCss = options?.css ?? [...registeredComponentCss].join('\n');
+    let stylesheet = parseCSS(DEFAULT_STYLESHEET + userCss);
+    // Console capture — only intercept when our IO owns the JS runtime's
+    // stdout/stderr (ProcessIO). With InProcessIO (browser, tests) console
+    // writes don't corrupt anything, so leave them alone. When intercepting,
+    // route to onConsole if provided; otherwise throw — silent suppression
+    // hides log calls and lengthens the feedback loop.
+    const onConsole = options?.onConsole;
+    const ownsStdio = io instanceof ProcessIO;
+    const levels = ['log', 'warn', 'error', 'info', 'debug'];
+    let restoreConsole = () => { };
+    if (ownsStdio) {
+        const originals = {
+            log: console.log.bind(console),
+            warn: console.warn.bind(console),
+            error: console.error.bind(console),
+            info: console.info.bind(console),
+            debug: console.debug.bind(console),
+        };
+        for (const level of levels) {
+            ;
+            console[level] = (...args) => {
+                if (onConsole) {
+                    onConsole({
+                        level,
+                        args: args.map(a => typeof a === 'string' ? a : JSON.stringify(a, null, 2) ?? String(a)),
+                        timestamp: Date.now(),
+                    });
+                    return;
+                }
+                throw new Error(`console.${level} would corrupt the terminal — pass an onConsole option to run() to route log output, or remove the call`);
+            };
+        }
+        restoreConsole = () => {
+            for (const level of levels) {
+                console[level] = originals[level];
+            }
+        };
+    }
     // Render context tracks mutations and determines minimum work
     const ctx = new RenderContext();
     const root = new TermNode('element', 'root');
     root.ctx = ctx;
-    // Color scheme detection — updated by polling
-    let detectedScheme = 'dark';
+    // Color scheme detection — updated by polling unless the host
+    // overrode it via options.colorScheme.
+    const colorSchemeOverride = options?.colorScheme;
+    let detectedScheme = colorSchemeOverride ?? 'dark';
     // Wire schedule callback (defined below, hoisted via closure)
     ctx.onScheduleRender = () => scheduleRender();
     // Persisted render state
+    /** What the terminal currently shows (selection overlay included). */
     let prevBuffer = null;
+    /** The last paint without the selection overlay — diff/extraction base. */
+    let prevClean = null;
+    const selection = new SelectionController(() => prevClean);
+    const inlineScreen = new InlineScreen();
+    if (inline) {
+        registerInlineHooks(root, { releaseTop: n => inlineScreen.releaseTop(n) });
+    }
+    /** Learn where the inline zone starts so mouse coordinates can map. */
+    const queryInlineOrigin = () => {
+        // The terminal reports where the cursor is, which is wherever the
+        // last render left it *within* the zone — snapshot that at the
+        // moment the query bytes go out (queries queue behind others).
+        let cursorRowAtQuery = 0;
+        router.query('\x1b[6n', matchCPR, 200, () => { cursorRowAtQuery = inlineScreen.cursorZoneRow(); }).then(reply => {
+            const row = parseCPRRow(reply);
+            if (row !== null)
+                inlineScreen.setOriginRow(Math.max(1, row - cursorRowAtQuery));
+        }).catch(() => { });
+    };
+    /** The buffer as displayed: the clean paint plus any selection. */
+    const overlayed = (buffer) => {
+        const range = selection.range();
+        if (!range)
+            return buffer;
+        const display = buffer.clone();
+        applySelectionOverlay(display, range);
+        return display;
+    };
+    /** Re-diff after a selection change without repainting the tree. */
+    const redrawSelection = () => {
+        if (!prevClean)
+            return;
+        const display = overlayed(prevClean);
+        const output = diffBuffers(prevBuffer, display);
+        if (output.length > 0)
+            writeOutput(output);
+        prevBuffer = display;
+    };
     let lastStyles;
     let lastFilteredStylesheet = null;
     let lastLayout;
     let renderScheduled = false;
     let initialRegistrationDone = false;
+    // CSS animations — reapply the current keyframe and repaint while live
+    const animationClock = new AnimationClock();
+    animationClock.onFrame = () => {
+        if (!lastStyles)
+            return;
+        const dirty = animationClock.apply(lastStyles);
+        if (dirty.length === 0)
+            return;
+        for (const { node, touchesLayout } of dirty) {
+            if (touchesLayout)
+                ctx.queue.enqueueLayoutBubble(node);
+            else
+                ctx.queue.enqueuePaintOnly(node);
+        }
+        scheduleRender();
+    };
     const scheduleRender = () => {
         if (renderScheduled)
             return;
@@ -54,25 +186,46 @@ export function run(AppComponent, options) {
     };
     const processQueue = () => {
         const snap = ctx.queue.snapshot();
-        if (snap.fullRecompute || !lastStyles || !lastLayout) {
+        const dirty = snap.paintOnly.size > 0 || snap.styleResolve.size > 0
+            || snap.layoutSubtree.size > 0 || snap.layoutBubble.size > 0;
+        if (inline) {
+            // The live area is content-sized, so any change can move
+            // everything — always render fully.
+            if (snap.fullRecompute || dirty || !lastStyles)
+                fullRender();
+        }
+        else if (snap.fullRecompute || !lastStyles || !lastLayout) {
             // Full recompute — initial render, resize, or CSS reload
             fullRender();
         }
-        else if (snap.paintOnly.size > 0 || snap.styleResolve.size > 0
-            || snap.layoutSubtree.size > 0 || snap.layoutBubble.size > 0) {
+        else if (dirty) {
             // Incremental render
             incrementalRender(snap);
         }
     };
-    const fullRender = () => {
-        const size = getTerminalSize();
-        // Set root dimensions so children can use percentage width/height
+    // Synchronized output (DEC 2026) is on until detection says otherwise —
+    // terminals that don't know the mode ignore it.
+    let syncOutput = true;
+    const writeOutput = (data) => {
+        io.write(syncOutput ? ansi.beginSyncUpdate() + data + ansi.endSyncUpdate() : data);
+    };
+    // Kitty-graphics layer — off until capability detection turns it on.
+    const graphicsLayer = new GraphicsLayer();
+    let graphicsEnabled = false;
+    /** The per-frame tail written after the cell diff: cursor + images. */
+    const frameTail = () => {
+        const cursor = emitFocusCursor(root, focusManager.focused);
+        return graphicsEnabled ? cursor + graphicsLayer.render(root, lastLayout) : cursor;
+    };
+    /** Resolve styles + layout for the current terminal size. */
+    const resolveForRender = (size) => {
         root.attributes.set('data-width', String(size.width));
         root.attributes.set('data-height', String(size.height));
-        const buffer = new CellBuffer(size.width, size.height);
         const media = { colorScheme: detectedScheme, displayMode: 'terminal', width: size.width, height: size.height };
         lastFilteredStylesheet = stylesheet ? filterByMedia(stylesheet, media) : null;
-        lastStyles = lastFilteredStylesheet ? resolveStyles(root, lastFilteredStylesheet) : undefined;
+        // Passing `media` here threads colorScheme into computeStyle so
+        // light-dark() resolves against the active scheme.
+        lastStyles = lastFilteredStylesheet ? resolveStyles(root, lastFilteredStylesheet, media) : undefined;
         // Ensure root style has terminal dimensions for percentage resolution
         if (lastStyles) {
             const rootStyle = lastStyles.get(root.id);
@@ -81,28 +234,92 @@ export function run(AppComponent, options) {
                 rootStyle.height = size.height;
             }
         }
+        if (lastStyles && lastFilteredStylesheet) {
+            animationClock.sync(root, lastStyles, getKeyframes(lastFilteredStylesheet), {
+                variables: collectVariables(root, lastFilteredStylesheet),
+                scheme: detectedScheme,
+            });
+            animationClock.syncTransitions(root, lastStyles);
+            animationClock.apply(lastStyles);
+        }
         lastLayout = lastStyles ? computeLayout(root, lastStyles, size.width, size.height) : undefined;
-        if (lastLayout)
+        if (lastLayout) {
             syncLayoutCache(root, lastLayout);
+            clampScrollPositions(root, lastLayout, io);
+        }
+    };
+    const fullRender = () => {
+        if (inline) {
+            inlineRender();
+            return;
+        }
+        const size = io.getSize();
+        const buffer = new CellBuffer(size.width, size.height);
+        resolveForRender(size);
         paint(root, buffer, lastStyles, lastLayout);
-        const output = diffBuffers(prevBuffer, buffer);
+        prevClean = buffer;
+        const display = overlayed(buffer);
+        const output = diffBuffers(prevBuffer, display) + frameTail();
         if (output.length > 0)
             writeOutput(output);
-        prevBuffer = buffer;
+        prevBuffer = display;
         // Register focusable elements after initial render
         if (!initialRegistrationDone) {
             registerFocusableNodes(root, focusManager);
             initialRegistrationDone = true;
         }
     };
+    /**
+     * Inline mode always renders fully: the live area is content-sized
+     * (clamped to the terminal height — archive to keep it short) and the
+     * InlineScreen driver emits relative-movement diffs.
+     */
+    const inlineRender = () => {
+        const size = io.getSize();
+        resolveForRender(size);
+        const rootBox = lastLayout?.get(root.id);
+        const extent = lastLayout && rootBox
+            ? contentExtent(root, lastLayout, rootBox)
+            : { width: size.width, height: 1 };
+        const height = Math.max(1, Math.min(extent.height, size.height));
+        const buffer = new CellBuffer(size.width, height);
+        paint(root, buffer, lastStyles, lastLayout);
+        prevClean = buffer;
+        let output = inlineScreen.render(buffer);
+        const pos = focusManager.focused?.getCursorScreenPos();
+        if (pos && pos.inViewport && pos.y < height) {
+            output += inlineScreen.moveCursorTo(pos.x, pos.y)
+                + ansi.setCursorShape('bar') + ansi.showCursor();
+        }
+        else {
+            output += ansi.hideCursor() + ansi.resetCursorShape();
+        }
+        if (graphicsEnabled)
+            output += graphicsLayer.render(root, lastLayout);
+        if (output.length > 0)
+            writeOutput(output);
+        if (!initialRegistrationDone) {
+            registerFocusableNodes(root, focusManager);
+            initialRegistrationDone = true;
+        }
+    };
     const incrementalRender = (snap) => {
-        const size = getTerminalSize();
+        const size = io.getSize();
         // Mutable copies for promoted nodes during processing
         const layoutSubtree = new Set(snap.layoutSubtree);
         const layoutBubble = new Set(snap.layoutBubble);
         // Step 1: Incremental style resolution
         if (snap.styleResolve.size > 0 && lastStyles && lastFilteredStylesheet) {
-            lastStyles = resolveStylesIncremental(root, lastFilteredStylesheet, lastStyles, snap.styleResolve, undefined, (node) => { layoutSubtree.add(node); });
+            const resolvedIds = new Set();
+            lastStyles = resolveStylesIncremental(root, lastFilteredStylesheet, lastStyles, snap.styleResolve, (nodeId) => { resolvedIds.add(nodeId); }, (node) => { layoutSubtree.add(node); }, detectedScheme);
+            // Newly mounted or restyled nodes may start/stop animations,
+            // and re-resolution resets styles to their base keyframe.
+            animationClock.sync(root, lastStyles, getKeyframes(lastFilteredStylesheet), {
+                variables: collectVariables(root, lastFilteredStylesheet),
+                scheme: detectedScheme,
+            });
+            animationClock.syncTransitions(root, lastStyles, resolvedIds);
+            animationClock.apply(lastStyles);
         }
         // Step 2: Incremental layout
         if (layoutSubtree.size > 0 || layoutBubble.size > 0) {
@@ -125,21 +342,25 @@ export function run(AppComponent, options) {
                 dirtyPaintNodes.add(node);
         }
         const hasScroll = hasScrolledNode(root);
-        if (noLayoutChanges && !hasScroll && dirtyPaintNodes.size > 0 && prevBuffer && lastStyles && lastLayout) {
-            const buffer = prevBuffer.clone();
+        if (noLayoutChanges && !hasScroll && dirtyPaintNodes.size > 0 && prevClean && lastStyles && lastLayout) {
+            const buffer = prevClean.clone();
             paintNodes(dirtyPaintNodes, buffer, lastStyles, lastLayout, root);
-            const output = diffBuffers(prevBuffer, buffer);
+            prevClean = buffer;
+            const display = overlayed(buffer);
+            const output = diffBuffers(prevBuffer, display) + frameTail();
             if (output.length > 0)
                 writeOutput(output);
-            prevBuffer = buffer;
+            prevBuffer = display;
         }
         else {
             const buffer = new CellBuffer(size.width, size.height);
             paint(root, buffer, lastStyles, lastLayout);
-            const output = diffBuffers(prevBuffer, buffer);
+            prevClean = buffer;
+            const display = overlayed(buffer);
+            const output = diffBuffers(prevBuffer, display) + frameTail();
             if (output.length > 0)
                 writeOutput(output);
-            prevBuffer = buffer;
+            prevBuffer = display;
         }
     };
     const focusManager = new FocusManager();
@@ -167,28 +388,56 @@ export function run(AppComponent, options) {
         unregisterFocusableNodes(child, focusManager);
         child.cleanup();
     };
-    enableRawMode();
+    io.enableRawMode();
     if (fullscreen)
-        enterFullscreen();
+        enterFullscreen(io);
+    // Cursor visibility is owned at the run-lifecycle level, not by
+    // enterFullscreen — non-fullscreen runs need it hidden too. The
+    // post-paint emitter takes over from here, showing the cursor only
+    // when something asks for it (focused input, region cursor).
+    io.write(ansi.hideCursor());
     // Write mode sequences directly — sync update wrapping can interfere
-    process.stdout.write(ansi.enableBracketedPaste());
+    io.write(ansi.enableBracketedPaste());
+    // Kitty keyboard protocol: unsupported terminals ignore the push/pop
+    io.write(ansi.pushKittyKeyboard());
     if (mouseEnabled)
-        process.stdout.write(ansi.enableMouse());
+        io.write(ansi.enableMouse());
     // Single stdin router — all input flows through here
-    const router = new StdinRouter();
+    const router = new StdinRouter(io);
     const handleKeyData = (data) => {
         const key = parseKeyEvent(data);
         if (!key)
             return;
         if (key.ctrl && key.key === 'c') {
             doCleanup();
-            process.exit(0);
+            if (typeof process !== 'undefined')
+                process.exit(0);
+            return;
         }
-        if (key.ctrl && key.key === 'z') {
+        if (key.ctrl && key.key === 'd' && exitOn.includes('ctrl+d')) {
             doCleanup();
-            process.kill(process.pid, 'SIGTSTP');
+            if (typeof process !== 'undefined')
+                process.exit(0);
+            return;
+        }
+        if (key.ctrl && key.key === 'z') {
+            suspend();
             return;
         }
+        // An open <dialog> captures keys: Escape closes it, Tab traps inside
+        const modal = activeModal(root);
+        focusManager.setScope(modal);
+        if (modal && key.key === 'Escape') {
+            modal.attributes.delete('open');
+            ctx.onRemoveAttribute(modal, 'open');
+            dispatchEvent(modal, 'close');
+            focusManager.setScope(null);
+            scheduleRender();
+            return;
+        }
+        if (modal && focusManager.focused && !withinSubtree(focusManager.focused, modal)) {
+            focusManager.focusNext(); // pull focus into the modal
+        }
         if (key.key === 'Tab' && key.shift) {
             focusManager.focusPrevious();
             scheduleRender();
@@ -201,6 +450,8 @@ export function run(AppComponent, options) {
         }
         if (key.key === 'Enter' && focusManager.focused) {
             const target = focusManager.focused;
+            if (hasBooleanAttribute(target, 'disabled'))
+                return;
             const event = dispatchEvent(target, 'click');
             // Default action: open links in browser (unless preventDefault was called)
             if (!event.defaultPrevented && target.tag === 'a') {
@@ -208,12 +459,35 @@ export function run(AppComponent, options) {
                 if (href)
                     openUrl(href);
             }
+            if (!event.defaultPrevented && target.tag === 'summary')
+                toggleDetails(target);
+            if (!event.defaultPrevented && target.tag === 'select')
+                cycleSelect(target, 1);
+            scheduleRender();
+            return;
+        }
+        // Space toggles a focused checkbox or selects a focused radio
+        if (key.key === ' ' && focusManager.focused && isCheckableInput(focusManager.focused)) {
+            toggleCheckable(focusManager.focused);
             scheduleRender();
             return;
         }
+        // A focused select cycles its options (popup-less interaction)
+        if (focusManager.focused?.tag === 'select') {
+            if (key.key === 'ArrowUp') {
+                cycleSelect(focusManager.focused, -1);
+                scheduleRender();
+                return;
+            }
+            if (key.key === 'ArrowDown' || key.key === ' ') {
+                cycleSelect(focusManager.focused, 1);
+                scheduleRender();
+                return;
+            }
+        }
         // Text input for focused input/textarea
         const focused = focusManager.focused;
-        if (focused && (focused.tag === 'input' || focused.tag === 'textarea')) {
+        if (focused && (focused.tag === 'input' || focused.tag === 'textarea') && !isCheckableInput(focused)) {
             if (!focused.textBuffer)
                 focused.textBuffer = new TextBuffer(focused.attributes.get('value') ?? '');
             if (focused.textBuffer.handleKey(key)) {
@@ -236,10 +510,18 @@ export function run(AppComponent, options) {
         }
     };
     const handleMouseData = (data) => {
-        const mouse = parseMouseEvent(data);
+        let mouse = parseMouseEvent(data);
         if (!mouse)
             return;
-        handleMouse(mouse, root, lastLayout, focusManager, scheduleRender, lastStyles, ctx);
+        if (inline) {
+            // Mouse rows are screen-absolute; the zone origin comes from a
+            // CPR query. Events above the zone (shell history) are ignored.
+            const zoneRow = inlineScreen.screenRowToZone(mouse.row, io.getSize().height);
+            if (zoneRow === null)
+                return;
+            mouse = { ...mouse, row: zoneRow };
+        }
+        handleMouse(mouse, root, lastLayout, focusManager, scheduleRender, lastStyles, ctx, io, selection, redrawSelection);
     };
     const handlePaste = (text) => {
         const focused = focusManager.focused;
@@ -262,27 +544,70 @@ export function run(AppComponent, options) {
         }
     };
     router.start({ onKey: handleKeyData, onMouse: handleMouseData, onPaste: handlePaste });
-    // Debug server (opt-in)
+    // Debug server (opt-in, dynamically imported to avoid ws dependency in browser)
     let debugServer = null;
     let consoleDomain = null;
     if (debugEnabled) {
-        debugServer = new DebugServer(debugPort);
-        consoleDomain = new ConsoleDomain(debugServer);
-        debugServer.registerDomain('Console', consoleDomain);
-        consoleDomain.start();
-        debugServer.start();
+        Promise.all([
+            import('./debug/server.js'),
+            import('./debug/console.js'),
+            import('./debug/dom.js'),
+            import('./debug/css.js'),
+        ]).then(([{ DebugServer }, { ConsoleDomain }, { DomDomain }, { CssDomain }]) => {
+            debugServer = new DebugServer(debugPort);
+            consoleDomain = new ConsoleDomain(debugServer);
+            const debugCtx = {
+                root,
+                styles: () => lastStyles,
+                layout: () => lastLayout,
+                requestRender: () => { ctx.queue.setFullRecompute(); scheduleRender(); },
+            };
+            debugServer.registerDomain('Console', consoleDomain);
+            debugServer.registerDomain('DOM', new DomDomain(debugCtx));
+            debugServer.registerDomain('CSS', new CssDomain(debugCtx));
+            consoleDomain.start();
+            debugServer.start();
+        });
     }
     // Serialised color scheme detection via router query
     const detectScheme = async () => {
         const result = await router.query('\x1b]11;?\x07', matchOSC11, 200);
         return result ? parseOSC11Scheme(result) : 'dark';
     };
-    // Render immediately with default scheme
+    // Render immediately with default scheme. Seed a Svelte context so
+    // descendant components can detect they're rendered in the svelterm
+    // target (vs plain browser-Svelte) without resorting to globals —
+    // important for components like EmbeddedTerminal that branch their
+    // render path. Browser-Svelte mounts have no such key, so a
+    // `getContext` call there returns undefined and the component
+    // defaults to the browser path.
     ctx.queue.setFullRecompute();
-    const { unmount: svUnmount } = renderer.render(AppComponent, { target: root, props: options?.props ?? {} });
+    const app = mount(AppComponent, {
+        renderer,
+        target: root,
+        props: options?.props ?? {},
+        context: new Map([[Symbol.for('@svelterm/target'), 'terminal']]),
+    });
+    const svUnmount = () => void unmount(app);
+    // Collect CSS from injected <style> elements (css: 'injected' mode).
+    // Skipped when the host passed an explicit `css` option.
+    if (!userCss) {
+        const injectedCss = collectInjectedCss(root);
+        if (injectedCss) {
+            stylesheet = parseCSS(DEFAULT_STYLESHEET + injectedCss);
+        }
+    }
     scheduleRender();
-    setupResizeHandler(() => { ctx.onResize(); prevBuffer = null; scheduleRender(); });
-    // Detect color scheme in background and re-render if different
+    io.onResize(() => {
+        ctx.onResize();
+        prevBuffer = null;
+        scheduleRender();
+        // Rewrap may have moved the zone — re-learn where it starts
+        if (inline && io instanceof ProcessIO)
+            queryInlineOrigin();
+    });
+    // Detect color scheme in background and re-render if different.
+    // Skipped when the host pinned a scheme via options.colorScheme.
     let pollRunning = true;
     const pollScheme = async () => {
         if (!pollRunning)
@@ -291,7 +616,8 @@ export function run(AppComponent, options) {
             const scheme = await detectScheme();
             if (scheme !== detectedScheme) {
                 detectedScheme = scheme;
-                lastFilteredStylesheet = stylesheet ? filterByMedia(stylesheet, { colorScheme: detectedScheme, displayMode: 'terminal', width: getTerminalSize().width, height: getTerminalSize().height }) : null;
+                const size = io.getSize();
+                lastFilteredStylesheet = stylesheet ? filterByMedia(stylesheet, { colorScheme: detectedScheme, displayMode: 'terminal', width: size.width, height: size.height }) : null;
                 ctx.onResize();
                 prevBuffer = null;
                 scheduleRender();
@@ -303,61 +629,209 @@ export function run(AppComponent, options) {
         if (pollRunning)
             setTimeout(pollScheme, 1000);
     };
-    pollScheme();
-    const appCleanup = createCleanup(svUnmount, fullscreen, mouseEnabled);
+    if (!colorSchemeOverride)
+        pollScheme();
+    // Detect terminal capabilities in the background: colour depth for
+    // SGR quantization, DEC 2026 support for frame batching. Only the
+    // real terminal answers queries; embedded IO keeps the defaults.
+    if (options?.colorDepth) {
+        ansi.setColorDepth(options.colorDepth);
+    }
+    else if (io instanceof ProcessIO) {
+        if (inline)
+            queryInlineOrigin();
+        detectCapabilities(router).then(caps => {
+            syncOutput = caps.syncOutput;
+            // Crisp images on kitty-graphics terminals; half-blocks stay
+            // in the buffer as the fallback and layout truth.
+            if (caps.graphics && !graphicsEnabled) {
+                graphicsEnabled = true;
+                scheduleRender();
+            }
+            if (caps.colorDepth === ansi.getColorDepth())
+                return;
+            ansi.setColorDepth(caps.colorDepth);
+            // Full repaint so every cell re-emits at the new depth
+            ctx.onResize();
+            prevBuffer = null;
+            scheduleRender();
+        }).catch(() => { });
+    }
     const doCleanup = () => {
         pollRunning = false;
+        animationClock.stop();
         router.stop();
         consoleDomain?.stop();
         debugServer?.stop();
-        appCleanup();
+        restoreConsole?.();
+        if (graphicsEnabled)
+            io.write(graphicsLayer.clear());
+        svUnmount();
+        if (mouseEnabled)
+            io.write(ansi.disableMouse());
+        io.write(ansi.popKittyKeyboard());
+        io.write(ansi.disableBracketedPaste());
+        if (fullscreen)
+            exitFullscreen(io);
+        if (inline) {
+            // Leave the rendered output in place; park the prompt below it.
+            io.write(inlineScreen.finish() + ansi.resetCursorShape());
+        }
+        else {
+            // Show cursor *after* exitFullscreen so it targets the main
+            // screen, not the alt screen we're leaving behind.
+            io.write(ansi.showCursor() + ansi.resetCursorShape());
+        }
+        io.disableRawMode();
+        io.dispose();
     };
-    process.on('SIGINT', () => { doCleanup(); process.exit(0); });
-    process.on('SIGTERM', () => { doCleanup(); process.exit(0); });
-    return doCleanup;
-}
-function createCleanup(unmountComponent, fullscreen, mouseEnabled) {
-    let cleaned = false;
-    return () => {
-        if (cleaned)
+    /**
+     * Ctrl+Z: release the terminal without unmounting, stop, and pick up
+     * where we left off on `fg` — modes re-enter and everything repaints.
+     */
+    const suspend = () => {
+        if (typeof process === 'undefined')
             return;
-        cleaned = true;
-        unmountComponent();
+        if (graphicsEnabled)
+            io.write(graphicsLayer.clear());
         if (mouseEnabled)
-            writeOutput(ansi.disableMouse());
-        writeOutput(ansi.disableBracketedPaste());
+            io.write(ansi.disableMouse());
+        io.write(ansi.popKittyKeyboard() + ansi.disableBracketedPaste());
         if (fullscreen)
-            exitFullscreen();
-        disableRawMode();
+            exitFullscreen(io);
+        if (inline)
+            inlineScreen.reset();
+        io.write(ansi.showCursor() + ansi.resetCursorShape());
+        io.disableRawMode();
+        process.kill(process.pid, 'SIGTSTP');
+    };
+    const resume = () => {
+        io.enableRawMode();
+        if (fullscreen)
+            enterFullscreen(io);
+        io.write(ansi.hideCursor() + ansi.enableBracketedPaste() + ansi.pushKittyKeyboard());
+        if (mouseEnabled)
+            io.write(ansi.enableMouse());
+        ctx.onResize();
+        prevBuffer = null;
+        prevClean = null;
+        scheduleRender();
+        if (inline && io instanceof ProcessIO)
+            queryInlineOrigin();
     };
+    if (typeof process !== 'undefined') {
+        process.on('SIGINT', () => { doCleanup(); process.exit(0); });
+        process.on('SIGTERM', () => { doCleanup(); process.exit(0); });
+        process.on('SIGCONT', resume);
+    }
+    const setColorScheme = (scheme) => {
+        // Host has spoken — silence the OSC-11 poller so it doesn't overwrite
+        // this value on its next 1s tick.
+        pollRunning = false;
+        if (scheme === detectedScheme)
+            return;
+        detectedScheme = scheme;
+        const size = io.getSize();
+        lastFilteredStylesheet = stylesheet ? filterByMedia(stylesheet, { colorScheme: detectedScheme, displayMode: 'terminal', width: size.width, height: size.height }) : null;
+        ctx.onResize();
+        prevBuffer = null;
+        scheduleRender();
+    };
+    return { cleanup: doCleanup, setColorScheme };
 }
-function handleMouse(mouse, root, layout, focusManager, scheduleRender, lastStyles, ctx) {
+const SCROLLBAR_VISIBLE_MS = 600;
+const SCROLLBAR_FADE_MS = 400;
+const SCROLLBAR_FADE_FRAMES = 16;
+const SCROLLBAR_TOTAL_MS = SCROLLBAR_VISIBLE_MS + SCROLLBAR_FADE_MS;
+let lastHoveredId = -1;
+function handleMouse(mouse, root, layout, focusManager, scheduleRender, lastStyles, ctx, io, selection, redrawSelection) {
     if (!layout)
         return;
-    // Handle hover — set data-hovered on element under cursor
+    // Handle hover — only update when the hovered element changes.
+    // Dragging with the left button extends the text selection.
     if (mouse.type === 'motion') {
+        if (mouse.button === 'left' && selection.onMotion(mouse.col, mouse.row)) {
+            redrawSelection();
+        }
         const target = hitTest(root, layout, mouse.col, mouse.row);
         const hoveredId = target?.id ?? -1;
-        // Walk tree and update data-hovered
-        updateHover(root, hoveredId, ctx);
-        scheduleRender();
+        if (hoveredId !== lastHoveredId) {
+            updateHover(root, hoveredId, ctx);
+            lastHoveredId = hoveredId;
+        }
+        return;
+    }
+    // Releasing the left button finishes a selection and copies it
+    if (mouse.type === 'release' && mouse.button === 'left') {
+        const text = selection.onRelease();
+        if (text)
+            copyToClipboard(text, data => io.write(data));
         return;
     }
     if (mouse.type !== 'press' && mouse.type !== 'scroll')
         return;
     if (mouse.button === 'left') {
+        const hadSelection = selection.range() !== null;
+        selection.onPress(mouse.col, mouse.row);
+        if (hadSelection || selection.range() !== null)
+            redrawSelection();
         const target = hitTest(root, layout, mouse.col, mouse.row);
         if (target) {
-            // Focus clicked element if it's focusable
+            // Disabled interactive elements swallow the click, as in browsers
+            if (FOCUSABLE_TAGS.has(target.tag ?? '') && hasBooleanAttribute(target, 'disabled'))
+                return;
             if (FOCUSABLE_TAGS.has(target.tag ?? '')) {
                 focusManager.focusByNode(target);
             }
+            if (isCheckableInput(target))
+                toggleCheckable(target);
             const event = dispatchEvent(target, 'click', mouse);
             if (!event.defaultPrevented && target.tag === 'a') {
                 const href = target.attributes.get('href');
                 if (href)
                     openUrl(href);
             }
+            if (!event.defaultPrevented && target.tag === 'summary')
+                toggleDetails(target);
+            if (!event.defaultPrevented && target.tag === 'select')
+                cycleSelect(target, 1);
+            // Clicking a label activates its control, as in browsers
+            if (!event.defaultPrevented) {
+                const control = labelledControl(target);
+                if (control && control !== target && !hasBooleanAttribute(control, 'disabled')) {
+                    if (FOCUSABLE_TAGS.has(control.tag ?? ''))
+                        focusManager.focusByNode(control);
+                    if (isCheckableInput(control))
+                        toggleCheckable(control);
+                }
+            }
+            scheduleRender();
+        }
+    }
+    else if (mouse.button === 'scrollLeft' || mouse.button === 'scrollRight') {
+        const target = hitTest(root, layout, mouse.col, mouse.row);
+        if (target) {
+            const scrollTarget = findScrollableAncestor(target, lastStyles);
+            if (scrollTarget) {
+                const box = layout.get(scrollTarget.id);
+                if (box) {
+                    const { width: contentWidth } = contentExtent(scrollTarget, layout, box);
+                    const viewportWidth = scrollTarget.tag === 'root'
+                        ? io.getSize().width
+                        : box.width;
+                    const maxScroll = Math.max(0, contentWidth - viewportWidth);
+                    const delta = mouse.button === 'scrollLeft' ? -1 : 1;
+                    scrollTarget.scrollLeft = Math.max(0, Math.min(scrollTarget.scrollLeft + delta, maxScroll));
+                    scrollTarget.hScrollbarVisibleUntil = Date.now() + SCROLLBAR_TOTAL_MS;
+                    const forceRepaint = () => { ctx.queue.setFullRecompute(); scheduleRender(); };
+                    const frameInterval = SCROLLBAR_FADE_MS / SCROLLBAR_FADE_FRAMES;
+                    for (let i = 0; i <= SCROLLBAR_FADE_FRAMES; i++) {
+                        setTimeout(forceRepaint, SCROLLBAR_VISIBLE_MS + i * frameInterval);
+                    }
+                    ctx.onScroll(scrollTarget);
+                }
+            }
+            dispatchEvent(target, 'scroll', mouse);
             scheduleRender();
         }
     }
@@ -368,13 +842,19 @@ function handleMouse(mouse, root, layout, focusManager, scheduleRender, lastStyl
             if (scrollTarget) {
                 const box = layout.get(scrollTarget.id);
                 if (box) {
-                    const contentHeight = scrollTarget.children.reduce((sum, c) => {
-                        const cBox = layout.get(c.id);
-                        return cBox ? Math.max(sum, cBox.y - box.y + cBox.height) : sum;
-                    }, 0);
-                    const delta = mouse.button === 'scrollUp' ? -3 : 3;
-                    const maxScroll = Math.max(0, contentHeight - box.height);
+                    const { height: contentHeight } = contentExtent(scrollTarget, layout, box);
+                    const viewportHeight = scrollTarget.tag === 'root'
+                        ? io.getSize().height
+                        : box.height;
+                    const maxScroll = Math.max(0, contentHeight - viewportHeight);
+                    const delta = mouse.button === 'scrollUp' ? -1 : 1;
                     scrollTarget.scrollTop = Math.max(0, Math.min(scrollTarget.scrollTop + delta, maxScroll));
+                    scrollTarget.scrollbarVisibleUntil = Date.now() + SCROLLBAR_TOTAL_MS;
+                    const forceRepaint = () => { ctx.queue.setFullRecompute(); scheduleRender(); };
+                    const frameInterval = SCROLLBAR_FADE_MS / SCROLLBAR_FADE_FRAMES;
+                    for (let i = 0; i <= SCROLLBAR_FADE_FRAMES; i++) {
+                        setTimeout(forceRepaint, SCROLLBAR_VISIBLE_MS + i * frameInterval);
+                    }
                     ctx.onScroll(scrollTarget);
                 }
             }
@@ -383,10 +863,7 @@ function handleMouse(mouse, root, layout, focusManager, scheduleRender, lastStyl
         }
     }
 }
-function setupResizeHandler(onResize) {
-    process.stdout.on('resize', onResize);
-}
-const FOCUSABLE_TAGS = new Set(['button', 'input', 'textarea', 'a', 'select']);
+const FOCUSABLE_TAGS = new Set(['button', 'input', 'textarea', 'a', 'select', 'summary']);
 function registerFocusableNodes(node, focusManager) {
     if (node.nodeType === 'element' && FOCUSABLE_TAGS.has(node.tag ?? '')) {
         focusManager.register(node);
@@ -421,6 +898,9 @@ function updateHover(node, hoveredId, ctx) {
 function findScrollableAncestor(node, styles) {
     let current = node;
     while (current) {
+        // Root element is implicitly scrollable (it's the viewport)
+        if (current.tag === 'root')
+            return current;
         const style = styles?.get(current.id);
         if (style && (style.overflow === 'scroll' || style.overflow === 'auto' || style.overflow === 'hidden')) {
             return current;
@@ -429,6 +909,42 @@ function findScrollableAncestor(node, styles) {
     }
     return null;
 }
+/** Clamp scroll positions on all nodes after resize/relayout. */
+function clampScrollPositions(node, layout, io) {
+    if (node.scrollTop !== 0 || node.scrollLeft !== 0) {
+        const box = layout.get(node.id);
+        if (box) {
+            const extent = contentExtent(node, layout, box);
+            const viewH = node.tag === 'root' ? io.getSize().height : box.height;
+            const viewW = node.tag === 'root' ? io.getSize().width : box.width;
+            const maxScrollY = Math.max(0, extent.height - viewH);
+            const maxScrollX = Math.max(0, extent.width - viewW);
+            if (node.scrollTop > maxScrollY)
+                node.scrollTop = maxScrollY;
+            if (node.scrollLeft > maxScrollX)
+                node.scrollLeft = maxScrollX;
+        }
+    }
+    for (const child of node.children)
+        clampScrollPositions(child, layout, io);
+}
+/** Find the maximum content extent of all descendants relative to the ancestor's position. */
+function contentExtent(node, layout, ancestorBox) {
+    let maxW = 0;
+    let maxH = 0;
+    function walk(n) {
+        const box = layout.get(n.id);
+        if (box) {
+            maxW = Math.max(maxW, box.x - ancestorBox.x + box.width);
+            maxH = Math.max(maxH, box.y - ancestorBox.y + box.height);
+        }
+        for (const child of n.children)
+            walk(child);
+    }
+    for (const child of node.children)
+        walk(child);
+    return { width: maxW, height: maxH };
+}
 function scrollIntoView(node, layout, styles, ctx) {
     if (!layout)
         return;
@@ -478,8 +994,21 @@ function findFirstElement(node) {
     }
     return node;
 }
+function collectInjectedCss(root) {
+    const parts = [];
+    for (const child of root.children) {
+        if (child.tag === 'style') {
+            parts.push(child.collectText());
+        }
+    }
+    return parts.join('\n');
+}
 export { TermNode } from './renderer/node.js';
 export { CellBuffer } from './render/buffer.js';
 export { parseCSS } from './css/parser.js';
 export { resolveStyles } from './css/compute.js';
 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';