svg-terminal 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,733 @@
+import * as zod from 'zod';
+
+/**
+ * Core type definitions for svg-terminal.
+ * All public interfaces used by the library, CLI, and plugins.
+ */
+/** Color palette for a terminal theme. */
+interface ThemeColors {
+    /** Primary text color */
+    text: string;
+    /** Muted/comment text */
+    comment: string;
+    /** Terminal background */
+    background: string;
+    /** Title bar background */
+    titleBarBackground: string;
+    /** Title bar text */
+    titleBarText: string;
+    /** Prompt color */
+    prompt: string;
+    /** Cursor color */
+    cursor: string;
+    /** Named semantic colors */
+    red: string;
+    green: string;
+    yellow: string;
+    blue: string;
+    magenta: string;
+    cyan: string;
+    white: string;
+    orange: string;
+    purple: string;
+    pink: string;
+    /** Bright variants */
+    brightRed: string;
+    brightGreen: string;
+    brightYellow: string;
+    brightBlue: string;
+    brightMagenta: string;
+    brightCyan: string;
+    brightWhite: string;
+    brightBlack: string;
+}
+/** A complete terminal theme. */
+interface Theme {
+    /** Theme name (e.g. "dracula") */
+    name: string;
+    /** Color palette */
+    colors: ThemeColors;
+    /** Title bar button colors */
+    buttons: {
+        close: string;
+        minimize: string;
+        maximize: string;
+    };
+}
+/** Window style variant. */
+type WindowStyle = 'macos' | 'win95' | 'floating' | 'minimal' | 'none';
+/** Window/SVG dimensions and chrome. */
+interface WindowConfig {
+    /** SVG width in pixels (default: 1000) */
+    width: number;
+    /** SVG height in pixels (default: 560, ~16:9 terminal ratio) */
+    height: number;
+    /** Border radius for window corners (default: 12) */
+    borderRadius: number;
+    /** Title bar height (default: 40) */
+    titleBarHeight: number;
+    /** Title text shown in title bar */
+    title: string;
+    /** Window style variant (default: 'macos') */
+    style: WindowStyle;
+    /** Auto-calculate height from content (default: false) */
+    autoHeight: boolean;
+    /** Minimum height when autoHeight is true (default: 300) */
+    minHeight: number;
+    /** Maximum height when autoHeight is true (default: 1200) */
+    maxHeight: number;
+}
+/** Terminal text rendering config. */
+interface TerminalTextConfig {
+    /** Font family stack (default: monospace) */
+    fontFamily: string;
+    /** Font size in pixels (default: 14) */
+    fontSize: number;
+    /** Line height multiplier (default: 1.8) */
+    lineHeight: number;
+    /** Left/right padding in pixels (default: 12) */
+    padding: number;
+    /** Top padding below title bar (default: 8) */
+    paddingTop: number;
+    /** Prompt string (default: "user@host:~$ ") */
+    prompt: string;
+}
+/** Animation timing presets. */
+interface TimingPresets {
+    typing: Record<string, number>;
+    pause: Record<string, number>;
+}
+/** Accessibility-related output toggles. */
+interface AccessibilityConfig {
+    /**
+     * Emit a `<desc>` child carrying the full final-frame content as plain
+     * text so screen readers can read more than the aria-label summary.
+     * Default: true. Set to false to skip duplicating output content into the
+     * SVG payload (e.g. if the output is sensitive).
+     */
+    describe: boolean;
+}
+/** SVG visual effects toggles. */
+interface EffectsConfig {
+    /** Enable phosphor text glow (default: false) */
+    textGlow: boolean;
+    /** Enable window drop shadow (default: true) */
+    shadow: boolean;
+    /** Enable CRT scanline effect (default: true) */
+    scanlines: boolean;
+    /**
+     * Subtle radial vignette over the terminal background (default: false).
+     * Auto-enabled for the three CRT-aesthetic themes (amber, green-phosphor,
+     * cyberpunk) via mergeConfig when the user hasn't set it. Mimics a real
+     * CRT's center-hot phosphor falloff.
+     */
+    vignette: boolean;
+}
+/** Animation timing configuration. */
+interface AnimationConfig {
+    /**
+     * Cursor blink cycle duration in ms (default: 1000).
+     * @deprecated As of v0.7.1 the cursor is solid-visible during typing —
+     *   the blink would render it invisible for chunks of the typing window,
+     *   which was the cursor-animation bug we fixed. Real terminals also
+     *   don't blink during active key input. Will be removed in v1.0.
+     */
+    cursorBlinkCycle: number;
+    /**
+     * Duration of character appear fade-in in ms (default: 10).
+     * @deprecated As of v0.7 typed-character reveal is discrete (one clip-path
+     *   animate per command); this field only affects the prompt fade-in and
+     *   the output-line fade-in. Will be removed in v1.0.
+     */
+    charAppearDuration: number;
+    /** Delay between output lines in ms (default: 50) */
+    outputLineStagger: number;
+    /** Pause after typing command before output appears in ms (default: 300) */
+    commandOutputPause: number;
+    /** Extra delay added to scroll events in ms (default: 10) */
+    scrollDelay: number;
+    /** Pause at end of output block in ms (default: 200) */
+    outputEndPause: number;
+    /** Default typing duration for commands in ms (default: 2000) */
+    defaultTypingDuration: number;
+    /** Default pause between sequences in ms (default: 1000) */
+    defaultSequencePause: number;
+    /** Loop control: true = infinite, false = play once, number = N times (default: true) */
+    loop: boolean | number;
+}
+/** Window chrome appearance configuration. */
+interface ChromeConfig {
+    /** Title bar font family — system UI stack by default, separate from terminal monospace */
+    titleFontFamily: string;
+    /** Title bar font size in px (default: 13) */
+    titleFontSize: number;
+    /** Window button radius in px (default: 6) */
+    buttonRadius: number;
+    /** Spacing between window buttons in px (default: 20) */
+    buttonSpacing: number;
+    /** Opacity for [[dim]] text (default: 0.6) */
+    dimOpacity: number;
+    /** Window button vertical center Y position (default: 16) */
+    buttonY: number;
+}
+/** Full terminal generator configuration. */
+interface TerminalConfig {
+    window: WindowConfig;
+    text: TerminalTextConfig;
+    theme: Theme;
+    effects: EffectsConfig;
+    animation: AnimationConfig;
+    chrome: ChromeConfig;
+    accessibility: AccessibilityConfig;
+    /** Maximum animation duration in seconds (default: 90) */
+    maxDuration: number;
+    /** Scroll animation duration in ms (default: 100) */
+    scrollDuration: number;
+    /** HTTP fetch timeout in ms for dynamic blocks (default: 10000) */
+    fetchTimeout: number;
+    /** Cache TTL in seconds for dynamic-block fetches (default: 86400 = 24h) */
+    cacheTTL: number;
+    /** Cache file path, relative to the config file (default: `.svg-terminal-cache.json`) */
+    cachePath: string;
+    /** Optional aria-label override for the generated SVG. When set, replaces
+     *  the auto-generated "Animated terminal showing: …" / "Static terminal
+     *  showing N lines" defaults. Useful for screen-reader-first profile
+     *  README labels. */
+    accessibilityLabel?: string;
+}
+/** A single animation sequence (command or output). */
+interface Sequence {
+    /** Sequence type */
+    type: 'command' | 'output';
+    /** Text content (when `frames` is set, this is the first frame joined). */
+    content: string;
+    /** Override prompt for this command */
+    prompt?: string;
+    /** Text color override */
+    color?: string;
+    /** Typing duration in ms (for commands) */
+    typingDuration?: number;
+    /** Pause after this sequence in ms */
+    pause?: number;
+    /** Delay before this sequence starts in ms */
+    delay?: number;
+    /** Optional multi-frame payload — output sequences only. Each entry is one frame's content (newline-separated lines). Triggers frame-cycle rendering. */
+    frames?: string[];
+    /** Frames per second when `frames` is set (default 4, capped at 30). */
+    framesFps?: number;
+    /** Loop frames forever when set (default true). */
+    framesLoop?: boolean;
+    /** Width-pinning opt-in (BlockResult.pinWidth). When true, output line text
+     *  elements emit `textLength` + `lengthAdjust="spacingAndGlyphs"`. */
+    pinWidth?: boolean;
+}
+/** An animation frame in the timeline. */
+interface AnimationFrame {
+    time: number;
+    type: 'scroll' | 'add-command' | 'add-output' | 'final';
+    lineIndex?: number;
+    prompt?: string;
+    command?: string;
+    content?: string;
+    color?: string;
+    typingDuration?: number;
+    scrollLines?: number;
+    bufferStart?: number;
+    /** Multi-frame payload — present only on add-output frames spawned from animated blocks. */
+    frames?: string[];
+    framesFps?: number;
+    framesLoop?: boolean;
+    /** Width-pinning opt-in from BlockResult.pinWidth. */
+    pinWidth?: boolean;
+}
+/** Context passed to blocks during rendering. */
+interface BlockContext {
+    /** Current date/time */
+    now: Date;
+    /** Terminal configuration */
+    config: TerminalConfig;
+    /** User-provided variables */
+    variables: Record<string, unknown>;
+    /**
+     * Cache helper. A block calls `useCache(key, () => fetchSomething())`
+     * to either return a cached payload (within TTL) or run the getter and
+     * write the result back to the cache file. Use a stable key — typically
+     * `${blockName}:${configHash}` so reconfigurations don't collide.
+     *
+     * Behavior is controlled by the runtime cache settings: enabled by
+     * default, bypassed under `--no-cache`, refreshed under
+     * `--refresh-cache`, and frozen (never fetch) under `--frozen-cache`.
+     */
+    useCache?<T>(key: string, getter: () => Promise<T>, opts?: {
+        ttl?: number;
+    }): Promise<T>;
+}
+/** A rendered block — produces sequences for the animation. */
+interface BlockResult {
+    /** The command to display being "typed" */
+    command: string;
+    /** Output lines (may contain [[fg:color]] markup). When `animation` is set, this is the FIRST frame — used as the static fallback and screen-reader snapshot. */
+    lines: string[];
+    /** Override color for output */
+    color?: string;
+    /** Typing speed preset name */
+    typing?: string;
+    /** Pause preset name after output */
+    pause?: string;
+    /**
+     * Optional frame-by-frame animation. Each frame is a `string[]` matching
+     * the column-width / line-count of `lines`. Renderer emits N text-group
+     * siblings with SMIL opacity-cycle animations. The static SVG (`--static`)
+     * and screen-reader `<desc>` use `lines` only.
+     */
+    animation?: BlockAnimation;
+    /**
+     * Optional signal: the block's render produced FALLBACK output (network
+     * failure, missing config, etc.) rather than the canonical live payload.
+     * Surfaces via `GenerateOptions.onCacheEvent('fallback', blockName)` so
+     * the CLI can warn users that a dynamic block didn't get its real data.
+     * Cacheable blocks (weather, github-stats, quote, fun-fact, github-languages)
+     * set this when they return their fallback lines.
+     */
+    fallback?: boolean;
+    /**
+     * Opt the output lines into width-pinning via SVG `textLength` +
+     * `lengthAdjust="spacingAndGlyphs"`. Use for blocks whose layout depends
+     * on a precise monospace advance (e.g. `neofetch`'s aligned columns) —
+     * forces the rendered width to our `CHAR_WIDTH_RATIO * fontSize` math
+     * regardless of the viewer's monospace fallback font.
+     *
+     * NOT recommended for blocks containing box-drawing characters (`╔═══╗`),
+     * full-width/double-width emoji, or other glyphs whose intrinsic widths
+     * vary by font — `spacingAndGlyphs` would scale them into looking worse.
+     * Defaults to false; existing blocks unaffected. (#85)
+     */
+    pinWidth?: boolean;
+}
+/** Multi-frame animation payload for a block. */
+interface BlockAnimation {
+    /** Frames in cycle order. Each entry is one frame's lines. */
+    frames: string[][];
+    /** Frames per second (default 4, capped at 30). */
+    fps?: number;
+    /** Loop forever (default true). When false, the final frame stays after one cycle. */
+    loop?: boolean;
+}
+/** Block definition — a self-contained terminal content module. */
+interface Block {
+    /** Block type name (e.g. "neofetch", "custom") */
+    name: string;
+    /** Human-readable description */
+    description?: string;
+    /**
+     * Optional zod schema for the block's config. When set, the YAML config entry
+     * is parsed through this schema BEFORE render() is called; failures throw
+     * BlockConfigError. Use `.strict()` on the schema so typos surface as errors
+     * rather than being silently stripped.
+     */
+    configSchema?: zod.ZodTypeAny;
+    /**
+     * Optional explicit list of config keys this block accepts. Used when
+     * configSchema is not set — unknown keys in the YAML produce a stderr
+     * warning (promoted to error under `--strict`). Keep this list synced with
+     * the actual destructures in render().
+     */
+    allowedKeys?: readonly string[];
+    /**
+     * True if this block reads via `context.useCache`. Used by the `cache check`
+     * CLI command to know which entries should have a cache record.
+     */
+    cacheable?: boolean;
+    /** Render the block content */
+    render(context: BlockContext, blockConfig: Record<string, unknown>): BlockResult | Promise<BlockResult>;
+}
+/** Block entry in user's YAML config. */
+interface BlockEntry {
+    /** Block type name */
+    block: string;
+    /** Block-specific configuration */
+    config?: Record<string, unknown>;
+    /** Override command text */
+    command?: string;
+    /** Override color */
+    color?: string;
+    /** Override typing speed */
+    typing?: string;
+    /** Override pause */
+    pause?: string;
+}
+/** User-facing YAML configuration schema. */
+interface UserConfig {
+    /** Theme name or custom theme object */
+    theme?: string | Theme;
+    /** Window dimensions */
+    window?: Partial<WindowConfig>;
+    /** Terminal text settings */
+    terminal?: Partial<TerminalTextConfig>;
+    /** Visual effects toggles */
+    effects?: Partial<EffectsConfig>;
+    /** Animation timing overrides */
+    animation?: Partial<AnimationConfig>;
+    /** Window chrome appearance overrides */
+    chrome?: Partial<ChromeConfig>;
+    /** Accessibility overrides */
+    accessibility?: Partial<AccessibilityConfig>;
+    /** Ordered list of blocks to render */
+    blocks: BlockEntry[];
+    /** User variables passed to blocks */
+    variables?: Record<string, unknown>;
+    /** Maximum animation duration in seconds */
+    maxDuration?: number;
+    /** Scroll animation duration in ms */
+    scrollDuration?: number;
+    /** Custom accessibility label for the SVG */
+    accessibilityLabel?: string;
+    /** HTTP fetch timeout in ms for dynamic blocks (default: 10000) */
+    fetchTimeout?: number;
+    /** Cache TTL in seconds for dynamic-block fetches (default: 86400 = 24h) */
+    cacheTTL?: number;
+    /** Cache file path, relative to the config file (default: `.svg-terminal-cache.json`) */
+    cachePath?: string;
+}
+/** A styled text span produced by the markup parser. */
+interface StyledSpan {
+    text: string;
+    fg: string | null;
+    bg: string | null;
+    bold: boolean;
+    dim: boolean;
+}
+/** Box drawing style. */
+type BoxStyle = 'double' | 'rounded' | 'single' | 'heavy' | 'dashed';
+/** Box character set for drawing. */
+interface BoxChars {
+    topLeft: string;
+    topRight: string;
+    bottomLeft: string;
+    bottomRight: string;
+    horizontal: string;
+    vertical: string;
+    separatorLeft: string;
+    separatorRight: string;
+}
+/** Configuration for creating an ASCII box. */
+interface BoxConfig {
+    /** Box style (default: 'double') */
+    style?: BoxStyle;
+    /** Total box width including borders (default: 56) */
+    width?: number;
+    /** Content lines */
+    lines: string[];
+    /** Line indices after which to add a separator */
+    separatorAfter?: number[];
+    /** Truncate lines that exceed width (default: true) */
+    truncate?: boolean;
+    /** Wrap lines that exceed width instead of truncating (default: false) */
+    wrap?: boolean;
+}
+
+/** Runtime cache mode driven by CLI flags. */
+type CacheMode = 'normal' | 'refresh' | 'frozen' | 'off';
+/** Per-entry status returned by checkCache(). */
+interface CacheCheckResult {
+    key: string;
+    blockName: string;
+    entryIndex: number;
+    /** OK = present + within TTL; STALE = present + expired; MISSING = no entry. */
+    status: 'OK' | 'STALE' | 'MISSING';
+    /** Age in seconds, present when status is OK or STALE. */
+    ageSeconds?: number;
+}
+
+/**
+ * SVG Terminal Generator — creates animated SVG terminals from sequences.
+ * This is the core rendering engine: sequences in, SVG string out.
+ */
+
+/** Generate an animated SVG terminal from a sequence of commands/outputs. */
+declare function generateSvg(sequences: Sequence[], config: TerminalConfig): string;
+/** Generate a static (non-animated) SVG terminal showing all content. */
+declare function generateStaticSvg(lines: string[], config: TerminalConfig): string;
+
+/**
+ * Configuration loading and merging.
+ * Reads YAML config files and merges with defaults.
+ */
+
+/**
+ * Load, parse, and validate a YAML config file. Throws ConfigError on any failure.
+ * js-yaml is loaded lazily so library consumers who only call `generate(parsedConfig)`
+ * don't pay for the parser in their bundle.
+ */
+declare function loadConfig(filePath: string): Promise<UserConfig>;
+/** Merge user config with defaults to produce a full TerminalConfig. */
+declare function mergeConfig(userConfig: UserConfig): TerminalConfig;
+
+/**
+ * Configuration errors with actionable, single-source-of-truth formatting.
+ * Thrown by loadConfig; the CLI renders them without a stack trace.
+ */
+/** A config-level error: bad YAML, schema violation, unknown theme/block. */
+declare class ConfigError extends Error {
+    /** Pre-formatted multi-line message ready for stderr. */
+    readonly formatted: string;
+    constructor(formatted: string);
+}
+/**
+ * A block-config validation failure: the block declares a configSchema (or an
+ * allowedKeys list under --strict) and the YAML entry violated it.
+ *
+ * Sibling of ConfigError so the CLI can render both with the same path —
+ * pattern-match on `err.formatted` either way.
+ */
+declare class BlockConfigError extends Error {
+    readonly formatted: string;
+    readonly blockName: string;
+    readonly entryIndex: number;
+    constructor(blockName: string, entryIndex: number, formatted: string);
+}
+
+/**
+ * Block registry — manages available block types.
+ * Blocks are self-contained terminal content modules.
+ */
+
+/** Register a block type. */
+declare function registerBlock(block: Block): void;
+/** Get a registered block by name. */
+declare function getBlock(name: string): Block | undefined;
+/** Get all registered block names. */
+declare function listBlocks(): string[];
+/** Register multiple blocks at once. */
+declare function registerBlocks(blocks: Block[]): void;
+
+/**
+ * Built-in blocks — register all default block types.
+ */
+/** Register all built-in blocks. */
+declare function registerBuiltinBlocks(): void;
+
+/**
+ * ASCII Box Generator — creates formatted boxes for terminal output.
+ *
+ * Supports multiple styles: double, rounded, single, heavy, dashed.
+ */
+
+/** Create an ASCII box with automatic padding and alignment. */
+declare function createBox(config: BoxConfig): string;
+/** Convenience: create a double-line box. */
+declare function createDoubleBox(lines: string[], width?: number, separatorAfter?: number[]): string;
+/** Convenience: create a rounded box. */
+declare function createRoundedBox(lines: string[], width?: number, separatorAfter?: number[]): string;
+/** Create a titled box with a header section separated from content. */
+declare function createTitledBox(opts: {
+    title: string;
+    subtitle?: string;
+    content: string[];
+    width?: number;
+    style?: BoxStyle;
+}): string;
+/** Configuration for auto-sizing boxes. */
+interface AutoBoxConfig {
+    lines: string[];
+    style?: BoxStyle;
+    minWidth?: number;
+    maxWidth?: number;
+    separatorAfter?: number[];
+}
+/** Create a box that auto-sizes to fit its content. */
+declare function createAutoBox(config: AutoBoxConfig): string;
+
+/**
+ * Markup parser for [[style]] formatted text.
+ * Converts template output to styled spans for SVG rendering.
+ *
+ * Supported tags:
+ * - [[fg:colorName]]text[[/fg]] — foreground color
+ * - [[bg:colorName]]text[[/bg]] — background color
+ * - [[bold]]text[[/bold]] — bold weight
+ * - [[dim]]text[[/dim]] — dimmed opacity
+ */
+
+/** Build a color lookup map from theme colors. */
+declare function buildColorMap(colors: ThemeColors): Record<string, string>;
+/** Parse [[style]] markup into styled spans. */
+declare function parseMarkup(text: string, colorMap: Record<string, string>, fallbackColor: string): StyledSpan[];
+/** Check if text contains [[]] markup. */
+declare function hasMarkup(text: string): boolean;
+/**
+ * Strip all markup and return plain text. The inner class is bounded to
+ * 256 chars to defuse the polynomial-ReDoS risk that CodeQL flagged on
+ * the unbounded form (`/\[\[[^\]]+\]\]/`). Every legitimate markup tag
+ * fits — `[[fg:hexNNNNNN]]`, `[[bold]]`, `[[dim]]` are all <20 chars —
+ * so the cap doesn't lose real input; it only kills the attacker's
+ * backtrack runway.
+ */
+declare function stripMarkup(text: string): string;
+
+/** Dracula color theme — https://draculatheme.com/ */
+declare const dracula: Theme;
+
+/** Nord color theme — https://www.nordtheme.com/ */
+declare const nord: Theme;
+
+/** Monokai Pro color theme */
+declare const monokai: Theme;
+
+/** Amber CRT — classic 1980s phosphor terminal (VT100/DEC aesthetic) */
+declare const amber: Theme;
+
+/** Green Phosphor — classic hacker terminal (Matrix/Mr. Robot aesthetic) */
+declare const greenPhosphor: Theme;
+
+/** Cyberpunk — neon on dark (Night City aesthetic) */
+declare const cyberpunk: Theme;
+
+/** Solarized Dark — Ethan Schoonover's precision-designed color scheme */
+declare const solarizedDark: Theme;
+
+/** Windows 95 — classic Microsoft DOS/command prompt aesthetic */
+declare const win95: Theme;
+
+/** Catppuccin Mocha — https://catppuccin.com/palette (dark variant) */
+declare const catppuccin: Theme;
+
+/** Tokyo Night — https://github.com/folke/tokyonight.nvim (default storm variant) */
+declare const tokyoNight: Theme;
+
+/** Gruvbox Dark (medium) — https://github.com/morhetz/gruvbox */
+declare const gruvbox: Theme;
+
+/**
+ * High-contrast theme designed to clear WCAG AAA (≥7:1) for text and prompt
+ * on background. Useful for users with low vision, screen-readability needs,
+ * or anyone projecting an SVG terminal in a high-glare environment (slides,
+ * keynote backgrounds). Also reads well at very small thumbnail sizes.
+ *
+ * Pure black background + pure white text = 21:1. Accent colors are picked
+ * from a constrained palette where every one clears 7:1 on black:
+ *   #ffffff (white)   21:1
+ *   #ffff00 (yellow)  19.6:1
+ *   #00ffff (cyan)    16.7:1
+ *   #00ff00 (green)   15.3:1
+ *   #ff00ff (magenta) 9.0:1
+ *   #ff5555 (red)     5.7:1 — AA only; bumped from canonical red for visibility
+ *   #aaaaff (blue)    8.4:1 — lifted from pure blue (#0000ff = 2.4:1, AAA-fail)
+ *
+ * NOT for general README aesthetic use — this is a deliberately blunt
+ * instrument. The standard themes (dracula, nord, …) are the default UX.
+ */
+declare const highContrast: Theme;
+
+/** Built-in theme registry. */
+declare const themes: Record<string, Theme>;
+/**
+ * Register a custom theme. Mirrors registerBlock() — name shadows built-ins.
+ * Throws on the reserved name "random" (which triggers daily rotation).
+ */
+declare function registerTheme(theme: Theme): void;
+/** Get a registered theme by name (custom + built-in). */
+declare function getTheme(name: string): Theme | undefined;
+/** All theme names — custom first, then built-ins. */
+declare function listThemes(): string[];
+/** Resolve a theme by name. Supports 'random' for random selection. Throws if not found. */
+declare function resolveTheme(nameOrTheme: string | Theme): Theme;
+
+/**
+ * Default configuration values for svg-terminal.
+ */
+
+/** Typing speed presets in milliseconds. */
+declare const TYPING_PRESETS: Record<string, number>;
+/** Pause duration presets in milliseconds. */
+declare const PAUSE_PRESETS: Record<string, number>;
+/** Resolve a typing speed from a preset name or number. */
+declare function resolveTyping(value: string | number | undefined): number;
+/** Resolve a pause duration from a preset name or number. */
+declare function resolvePause(value: string | number | undefined): number;
+
+/**
+ * Fetch a URL with a timeout. Returns the Response or null on failure.
+ * Never throws — all errors are caught and logged.
+ */
+declare function fetchWithTimeout(url: string, timeoutMs?: number): Promise<Response | null>;
+/**
+ * Fetch JSON from a URL with a timeout. Returns parsed data or null.
+ * Never throws — all errors are caught and logged.
+ */
+declare function fetchJson<T = unknown>(url: string, timeoutMs?: number): Promise<T | null>;
+/**
+ * Fetch plain text from a URL with a timeout. Returns text or null.
+ * Never throws — all errors are caught and logged.
+ */
+declare function fetchText(url: string, timeoutMs?: number): Promise<string | null>;
+
+/**
+ * svg-terminal — Generate animated SVG terminals for GitHub READMEs.
+ *
+ * @example
+ * ```ts
+ * import { generate } from 'svg-terminal';
+ *
+ * const svg = await generate({
+ *   theme: 'dracula',
+ *   window: { title: 'my-terminal' },
+ *   blocks: [
+ *     { block: 'neofetch', config: { username: 'dev', hostname: 'box' } },
+ *     { block: 'custom', config: { command: 'echo hi', lines: ['Hello!'] } },
+ *   ],
+ * });
+ * ```
+ */
+
+/** Cache + render event surfaced by `GenerateOptions.onCacheEvent`. */
+type CacheEventType = 'hit' | 'miss' | 'refreshed' | 'fallback';
+/** Options to thread cache runtime + file context into generate(). */
+interface GenerateOptions {
+    /** Absolute or relative path to the YAML config file — anchors cachePath resolution. */
+    configPath?: string;
+    /** Cache mode (default: 'normal'). Set via CLI flags --no-cache / --refresh-cache / --frozen-cache. */
+    cacheMode?: CacheMode;
+    /**
+     * Override the `context.now` passed to each block. Defaults to `new Date()`.
+     * Useful for reproducible demos + tests: pass a fixed Date so time-dependent
+     * blocks (ascii-clock, ascii-calendar, dice-roll's per-day seed, etc.)
+     * produce deterministic output.
+     */
+    now?: Date;
+    /**
+     * Optional callback for cache + render events. Called per cacheable-block
+     * `useCache` invocation (`'hit'` = served from cache within TTL, `'miss'` =
+     * fetched fresh, `'refreshed'` = forced refresh under `--refresh-cache`)
+     * AND once per block that returned `result.fallback === true` (failed to
+     * fetch live data, served defaults).
+     *
+     * `key` is the block's cache key for cache events (e.g.
+     * `"weather:abc123"`) OR the block's name for fallback events.
+     *
+     * The CLI uses this to print a one-line summary at the end of a generate
+     * run when dynamic blocks are involved — surfaces the
+     * "frozen-cache served a stale entry" / "network failed silently" cases
+     * that were previously invisible.
+     */
+    onCacheEvent?: (event: CacheEventType, key: string) => void;
+}
+/** Enable strict mode globally — unknown block-config keys throw instead of warning. */
+declare function setStrictBlockConfig(enabled: boolean): void;
+/**
+ * Generate an animated SVG terminal from a declarative config.
+ * This is the main API entry point.
+ */
+declare function generate(userConfig: UserConfig, options?: GenerateOptions): Promise<string>;
+/**
+ * Walk a config and report each cacheable block's status against the cache file.
+ * Returns one result per entry whose block declares `cacheable: true`.
+ * Used by the `svg-terminal cache check` CLI command.
+ */
+declare function inspectCache(userConfig: UserConfig, configPath: string): {
+    filePath: string;
+    results: CacheCheckResult[];
+};
+declare function generateStatic(userConfig: UserConfig, options?: GenerateOptions): Promise<string>;
+
+export { type AccessibilityConfig, type AnimationConfig, type AnimationFrame, type Block, type BlockAnimation, BlockConfigError, type BlockContext, type BlockEntry, type BlockResult, type BoxChars, type BoxConfig, type BoxStyle, type CacheEventType, type ChromeConfig, ConfigError, type EffectsConfig, type GenerateOptions, PAUSE_PRESETS, type Sequence, type StyledSpan, TYPING_PRESETS, type TerminalConfig, type TerminalTextConfig, type Theme, type ThemeColors, type TimingPresets, type UserConfig, type WindowConfig, type WindowStyle, amber, buildColorMap, catppuccin, createAutoBox, createBox, createDoubleBox, createRoundedBox, createTitledBox, cyberpunk, dracula, fetchJson, fetchText, fetchWithTimeout, generate, generateStatic, generateStaticSvg, generateSvg, getBlock, getTheme, greenPhosphor, gruvbox, hasMarkup, highContrast, inspectCache, listBlocks, listThemes, loadConfig, mergeConfig, monokai, nord, parseMarkup, registerBlock, registerBlocks, registerBuiltinBlocks, registerTheme, resolvePause, resolveTheme, resolveTyping, setStrictBlockConfig, solarizedDark, stripMarkup, themes, tokyoNight, win95 };