@sayknow-cli/tui 0.3.6 → 0.3.8

package/dist/types/terminal-capabilities.d.ts

@@ -0,0 +1,75 @@
+export declare enum ImageProtocol {
+    Kitty = "\u001B_G",
+    Iterm2 = "\u001B]1337;File=",
+    Sixel = "\u001BPq"
+}
+export declare enum NotifyProtocol {
+    Bell = "\u0007",
+    Osc99 = "\u001B]99;;",
+    Osc9 = "\u001B]9;"
+}
+export type TerminalId = "kitty" | "ghostty" | "wezterm" | "iterm2" | "vscode" | "alacritty" | "base" | "trueColor";
+/** Terminal capability details used for rendering and protocol selection. */
+export declare class TerminalInfo {
+    readonly id: TerminalId;
+    readonly imageProtocol: ImageProtocol | null;
+    readonly trueColor: boolean;
+    readonly hyperlinks: boolean;
+    readonly notifyProtocol: NotifyProtocol;
+    constructor(id: TerminalId, imageProtocol: ImageProtocol | null, trueColor: boolean, hyperlinks: boolean, notifyProtocol?: NotifyProtocol);
+    isImageLine(line: string): boolean;
+    formatNotification(message: string): string;
+    sendNotification(message: string): void;
+}
+export declare function isNotificationSuppressed(): boolean;
+/**
+ * Returns true when running in Windows Terminal with known SIXEL support.
+ *
+ * Windows Terminal introduced SIXEL support in preview 1.22.
+ */
+export declare function isWindowsTerminalPreviewSixelSupported(env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform): boolean;
+export declare const TERMINAL_ID: TerminalId;
+export declare const TERMINAL: TerminalInfo;
+/**
+ * Override terminal image protocol at runtime after capability probes complete.
+ */
+export declare function setTerminalImageProtocol(imageProtocol: ImageProtocol | null): void;
+export declare function getTerminalInfo(terminalId: TerminalId): TerminalInfo;
+export interface CellDimensions {
+    widthPx: number;
+    heightPx: number;
+}
+export interface ImageDimensions {
+    widthPx: number;
+    heightPx: number;
+}
+export interface ImageRenderOptions {
+    maxWidthCells?: number;
+    maxHeightCells?: number;
+    preserveAspectRatio?: boolean;
+}
+export declare function getCellDimensions(): CellDimensions;
+export declare function setCellDimensions(dims: CellDimensions): void;
+export declare function encodeKitty(base64Data: string, options?: {
+    columns?: number;
+    rows?: number;
+    imageId?: number;
+}): string;
+export declare function encodeITerm2(base64Data: string, options?: {
+    width?: number | string;
+    height?: number | string;
+    name?: string;
+    preserveAspectRatio?: boolean;
+    inline?: boolean;
+}): string;
+export declare function calculateImageRows(imageDimensions: ImageDimensions, targetWidthCells: number, cellDimensions?: CellDimensions): number;
+export declare function getPngDimensions(base64Data: string): ImageDimensions | null;
+export declare function getJpegDimensions(base64Data: string): ImageDimensions | null;
+export declare function getGifDimensions(base64Data: string): ImageDimensions | null;
+export declare function getWebpDimensions(base64Data: string): ImageDimensions | null;
+export declare function getImageDimensions(base64Data: string, mimeType: string): ImageDimensions | null;
+export declare function renderImage(base64Data: string, imageDimensions: ImageDimensions, options?: ImageRenderOptions): {
+    sequence: string;
+    rows: number;
+} | null;
+export declare function imageFallback(mimeType: string, dimensions?: ImageDimensions, filename?: string): string;

package/dist/types/terminal.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Whether SKC may reprogram the keyboard with enhanced input protocols
+ * (the Kitty keyboard protocol and the xterm modifyOtherKeys fallback).
+ *
+ * Enabled by default. Set `SKC_TUI_KEYBOARD_PROTOCOL=0` to leave the keyboard in
+ * its default mode. Some terminals — notably Android Termius — break IME
+ * composition (e.g. Korean/Hangul syllable composition) while these enhanced
+ * modes are active, committing every intermediate composing jamo/syllable
+ * instead of only the final character. Disabling the protocol restores normal
+ * IME behavior, matching how other TUIs that leave the keyboard untouched render
+ * Korean correctly.
+ */
+export declare function keyboardEnhancementEnabled(): boolean;
+/** Error codes for terminal/pipe write failures that should never crash the process. */
+export declare function isBenignTerminalWriteError(err: unknown): boolean;
+/**
+ * Emergency terminal restore - call this from signal/crash handlers
+ * Resets terminal state without requiring access to the ProcessTerminal instance
+ */
+export declare function emergencyTerminalRestore(): void;
+/** Terminal-reported appearance (dark/light mode). */
+export type TerminalAppearance = "dark" | "light";
+export interface Terminal {
+    start(onInput: (data: string) => void, onResize: () => void): void;
+    stop(): void;
+    /**
+     * Drain stdin before exiting to prevent Kitty key release events from
+     * leaking to the parent shell over slow SSH connections.
+     * @param maxMs - Maximum time to drain (default: 1000ms)
+     * @param idleMs - Exit early if no input arrives within this time (default: 50ms)
+     */
+    drainInput(maxMs?: number, idleMs?: number): Promise<void>;
+    write(data: string): void;
+    get available(): boolean;
+    get columns(): number;
+    get rows(): number;
+    get kittyProtocolActive(): boolean;
+    moveBy(lines: number): void;
+    hideCursor(): void;
+    showCursor(): void;
+    clearLine(): void;
+    clearFromCursor(): void;
+    clearScreen(): void;
+    setTitle(title: string): void;
+    setProgress(active: boolean): void;
+    /**
+     * Register a callback for terminal appearance (dark/light) changes.
+     * Detection uses OSC 11 background color query with Mode 2031 as a change trigger.
+     * Fires when the detected appearance changes, including the initial detection.
+     */
+    onAppearanceChange(callback: (appearance: TerminalAppearance) => void): void;
+    /** The last detected terminal appearance, or undefined if not yet known. */
+    get appearance(): TerminalAppearance | undefined;
+}
+interface TerminalSizeStream {
+    columns?: number;
+    rows?: number;
+    getWindowSize?: () => [number, number] | number[];
+}
+export declare function resolveTerminalColumns(stream?: TerminalSizeStream, envColumns?: string | undefined): number;
+export declare function resolveTerminalRows(stream?: TerminalSizeStream, envRows?: string | undefined): number;
+/**
+ * Real terminal using process.stdin/stdout
+ */
+export declare class ProcessTerminal implements Terminal {
+    #private;
+    get kittyProtocolActive(): boolean;
+    get appearance(): TerminalAppearance | undefined;
+    onAppearanceChange(callback: (appearance: TerminalAppearance) => void): void;
+    start(onInput: (data: string) => void, onResize: () => void): void;
+    drainInput(maxMs?: number, idleMs?: number): Promise<void>;
+    stop(): void;
+    write(data: string): void;
+    /** Invoked by the durable module-level stdout write guard (see installStdoutWriteGuard). */
+    markStdoutUnavailable(err: unknown): void;
+    get available(): boolean;
+    get columns(): number;
+    get rows(): number;
+    moveBy(lines: number): void;
+    hideCursor(): void;
+    showCursor(): void;
+    clearLine(): void;
+    clearFromCursor(): void;
+    clearScreen(): void;
+    setTitle(title: string): void;
+    setProgress(active: boolean): void;
+}
+export {};

package/dist/types/ttyid.d.ts

@@ -0,0 +1,9 @@
+/** Resolve the TTY device path for stdin (fd 0) via POSIX `ttyname(3)`. */
+export declare function getTtyPath(): string | null;
+/**
+ * Get a stable identifier for the current terminal.
+ * Uses the TTY device path (e.g., /dev/pts/3), falling back to environment
+ * variables for terminal multiplexers or terminal emulators.
+ * Returns null if no terminal can be identified (e.g., piped input).
+ */
+export declare function getTerminalId(): string | null;

package/dist/types/tui.d.ts

@@ -0,0 +1,206 @@
+import type { Terminal } from "./terminal";
+import { visibleWidth } from "./utils";
+type InputListenerResult = {
+    consume?: boolean;
+    data?: string;
+} | undefined;
+type InputListener = (data: string) => InputListenerResult;
+/**
+ * Component interface - all components must implement this
+ */
+export interface Component {
+    /**
+     * Render the component to lines for the given viewport width
+     * @param width - Current viewport width
+     * @returns Array of strings, each representing a line
+     */
+    render(width: number): string[];
+    /**
+     * Optional handler for keyboard input when component has focus
+     */
+    handleInput?(data: string): void;
+    /**
+     * If true, component receives key release events (Kitty protocol).
+     * Default is false - release events are filtered out.
+     */
+    wantsKeyRelease?: boolean;
+    /**
+     * Invalidate any cached rendering state.
+     * Called when theme changes or when component needs to re-render from scratch.
+     */
+    invalidate(): void;
+    /**
+     * Optional cleanup hook. Called once when the component is permanently
+     * removed from the tree via removeChild/clear/dispose. Implementations MUST
+     * be idempotent. Components meant to be re-added should be detached, not
+     * removed/cleared.
+     */
+    dispose?(): void;
+}
+/**
+ * Interface for components that can receive focus and display a hardware cursor.
+ * When focused, the component should emit CURSOR_MARKER at the cursor position
+ * in its render output. TUI will find this marker and position the hardware
+ * cursor there for proper IME candidate window positioning.
+ */
+export interface Focusable {
+    /** Set by TUI when focus changes. Component should emit CURSOR_MARKER when true. */
+    focused: boolean;
+}
+/** Type guard to check if a component implements Focusable */
+export declare function isFocusable(component: Component | null): component is Component & Focusable;
+/**
+ * Cursor position marker - APC (Application Program Command) sequence.
+ * This is a zero-width escape sequence that terminals ignore.
+ * Components emit this at the cursor position when focused.
+ * TUI finds and strips this marker, then positions the hardware cursor there.
+ */
+export declare const CURSOR_MARKER = "\u001B_pi:c\u0007";
+export { visibleWidth };
+/**
+ * Anchor position for overlays
+ */
+export type OverlayAnchor = "center" | "top-left" | "top-right" | "bottom-left" | "bottom-right" | "top-center" | "bottom-center" | "left-center" | "right-center";
+/**
+ * Margin configuration for overlays
+ */
+export interface OverlayMargin {
+    top?: number;
+    right?: number;
+    bottom?: number;
+    left?: number;
+}
+/** Value that can be absolute (number) or percentage (string like "50%") */
+export type SizeValue = number | `${number}%`;
+/**
+ * Options for overlay positioning and sizing.
+ * Values can be absolute numbers or percentage strings (e.g., "50%").
+ */
+export interface OverlayOptions {
+    /** Width in columns, or percentage of terminal width (e.g., "50%") */
+    width?: SizeValue;
+    /** Minimum width in columns */
+    minWidth?: number;
+    /** Maximum height in rows, or percentage of terminal height (e.g., "50%") */
+    maxHeight?: SizeValue;
+    /** Anchor point for positioning (default: 'center') */
+    anchor?: OverlayAnchor;
+    /** Horizontal offset from anchor position (positive = right) */
+    offsetX?: number;
+    /** Vertical offset from anchor position (positive = down) */
+    offsetY?: number;
+    /** Row position: absolute number, or percentage (e.g., "25%" = 25% from top) */
+    row?: SizeValue;
+    /** Column position: absolute number, or percentage (e.g., "50%" = centered horizontally) */
+    col?: SizeValue;
+    /** Margin from terminal edges. Number applies to all sides. */
+    margin?: OverlayMargin | number;
+    /**
+     * Control overlay visibility based on terminal dimensions.
+     * If provided, overlay is only rendered when this returns true.
+     * Called each render cycle with current terminal dimensions.
+     */
+    visible?: (termWidth: number, termHeight: number) => boolean;
+}
+/**
+ * Handle returned by showOverlay for controlling the overlay
+ */
+export interface OverlayHandle {
+    /** Permanently remove the overlay (cannot be shown again) */
+    hide(): void;
+    /** Temporarily hide or show the overlay */
+    setHidden(hidden: boolean): void;
+    /** Check if overlay is temporarily hidden */
+    isHidden(): boolean;
+}
+/**
+ * Container - a component that contains other components
+ */
+export declare class Container implements Component {
+    #private;
+    children: Component[];
+    addChild(component: Component): void;
+    removeChild(component: Component): void;
+    /** Remove a child without disposing it (for detach-then-readd reuse). */
+    detachChild(component: Component): void;
+    clear(): void;
+    /** Remove all children without disposing them (for detach-then-readd reuse). */
+    detachAll(): void;
+    dispose(): void;
+    invalidate(): void;
+    render(width: number): string[];
+}
+type TuiRenderCounterSnapshot = {
+    debugRedrawEnvReads: number;
+    debugRedrawAppendWrites: number;
+    differentialGuardVisibleWidthCalls: number;
+};
+/**
+ * TUI - Main class for managing terminal UI with differential rendering
+ */
+export declare class TUI extends Container {
+    #private;
+    terminal: Terminal;
+    /** Global callback for debug key (Shift+Ctrl+D). Called before input is forwarded to focused component. */
+    onDebug?: () => void;
+    static resetRenderCountersForTest(): void;
+    static getRenderCountersForTest(): TuiRenderCounterSnapshot;
+    overlayStack: {
+        component: Component;
+        options?: OverlayOptions;
+        preFocus: Component | null;
+        hidden: boolean;
+    }[];
+    constructor(terminal: Terminal, showHardwareCursor?: boolean);
+    dispose(): void;
+    get fullRedraws(): number;
+    getShowHardwareCursor(): boolean;
+    setShowHardwareCursor(enabled: boolean): void;
+    getClearOnShrink(): boolean;
+    /**
+     * Set whether to trigger full re-render when content shrinks.
+     * When true (default), empty rows are cleared when content shrinks.
+     * When false, empty rows remain (reduces redraws on slower terminals).
+     */
+    setClearOnShrink(enabled: boolean): void;
+    setFocus(component: Component | null): void;
+    setBottomPinnedComponent(component: Component | null): void;
+    scrollViewportPages(direction: -1 | 1): boolean;
+    followLiveViewport(): boolean;
+    /**
+     * Show an overlay component with configurable positioning and sizing.
+     * Returns a handle to control the overlay's visibility.
+     */
+    showOverlay(component: Component, options?: OverlayOptions): OverlayHandle;
+    /** Hide the topmost overlay and restore previous focus. */
+    hideOverlay(): void;
+    /** Check if there are any visible overlays */
+    hasOverlay(): boolean;
+    invalidate(): void;
+    start(): void;
+    get terminalAvailable(): boolean;
+    addInputListener(listener: InputListener): () => void;
+    removeInputListener(listener: InputListener): void;
+    stop(): void;
+    /**
+     * Viewport-repaint-aware resize render request.
+     *
+     * A forced full redraw (`requestRender(true)`) resets `#previousWidth`/`#previousHeight`
+     * to -1, which makes `#doRender` treat the frame as a width change and fall into the
+     * `fullRender` path. In terminal multiplexers that path skips the scrollback-clearing
+     * `3J` escape (users navigate scrollback history), so replaying every transcript line
+     * piles it back on top of scrollback — the "top of screen scrolls down to the prompt at
+     * high speed" resize storm. Windows Terminal can also visibly jump to the
+     * transcript top during streaming redraws, so viewport-repaint sessions keep
+     * force off and let `#doRender` repaint only the live viewport. Set
+     * `PI_TUI_LEGACY_MULTIPLEXER_FULL_RENDER=1` to restore the legacy tmux redraw.
+     */
+    requestResizeRender(): void;
+    requestRender(force?: boolean, source?: string): void;
+    getLineRenderCacheStats(): {
+        normalizationSize: number;
+        truncationSize: number;
+        normalizationLimit: number;
+        truncationLimit: number;
+    };
+}

package/dist/types/utils.d.ts

@@ -0,0 +1,87 @@
+import { Ellipsis, type ExtractSegmentsResult, type SliceResult } from "@sayknow-cli/natives";
+export { Ellipsis } from "@sayknow-cli/natives";
+export { getDefaultTabWidth, getIndentation } from "@sayknow-cli/utils";
+/** Test-only performance counters for advisory baseline tests. */
+export declare const __textHelperPerfCounters: {
+    truncateToWidthCalls: number;
+    wrapTextWithAnsiCalls: number;
+    truncateLinesToWidthCalls: number;
+    visibleWidthsCalls: number;
+    reset(): void;
+};
+export declare function invalidateTabWidthCache(): void;
+export declare function isPrintableAscii(text: string): boolean;
+export declare function sliceWithWidth(line: string, startCol: number, length: number, strict?: boolean | null): SliceResult;
+export declare function truncateToWidth(text: string, maxWidth: number, ellipsisKind?: Ellipsis | null, pad?: boolean | null): string;
+export declare function truncateLinesToWidth(lines: readonly string[], maxWidth: number, ellipsisKind?: Ellipsis | null, pad?: boolean | null): string[];
+export declare function wrapTextWithAnsi(text: string, width: number): string[];
+export declare function extractSegments(line: string, beforeEnd: number, afterStart: number, afterLen: number, strictAfter: boolean): ExtractSegmentsResult;
+/**
+ * Tab width in columns for `file`, using `process.cwd()` as the project root for relative paths.
+ */
+export declare function getIndentationNoescape(file?: string): number;
+export declare function replaceTabs(text: string, file?: string): string;
+/**
+ * Returns a string of n spaces. Uses a pre-allocated buffer for efficiency.
+ */
+export declare function padding(n: number): string;
+/**
+ * Get the shared grapheme segmenter instance.
+ */
+export declare function getSegmenter(): Intl.Segmenter;
+export declare function visibleWidthRaw(str: string): number;
+/**
+ * Calculate the visible width of a string in terminal columns.
+ */
+export declare function visibleWidth(str: string): number;
+export declare function visibleWidthsNative(lines: readonly string[]): number[];
+export declare function visibleWidths(lines: readonly string[]): number[];
+/**
+ * Normalize text for terminal output without changing logical editor content.
+ * Some terminals render canonically decomposed Hangul jamo or precomposed
+ * Thai/Lao AM vowels inconsistently during differential repaint. Emit a stable
+ * terminal form while keeping the component/source strings unchanged.
+ */
+export declare function normalizeTerminalOutput(str: string): string;
+/**
+ * Check if a character is whitespace.
+ */
+export declare function isWhitespaceChar(char: string): boolean;
+/**
+ * Check if a character is punctuation.
+ */
+export declare function isPunctuationChar(char: string): boolean;
+export type WordNavKind = "whitespace" | "delimiter" | "cjk" | "word" | "other";
+/**
+ * Coarse Unicode-aware character classification for word navigation (Option/Alt + Left/Right).
+ * This intentionally avoids language-specific word segmentation for predictability across scripts.
+ */
+export declare function getWordNavKind(grapheme: string): WordNavKind;
+export declare function isWordNavJoiner(grapheme: string): boolean;
+/**
+ * Move the cursor one "word" to the left using Unicode-aware coarse navigation.
+ *
+ * Returns a new cursor index in the range [0, text.length].
+ */
+export declare function moveWordLeft(text: string, cursor: number): number;
+/**
+ * Move the cursor one "word" to the right using Unicode-aware coarse navigation.
+ *
+ * Returns a new cursor index in the range [0, text.length].
+ */
+export declare function moveWordRight(text: string, cursor: number): number;
+/**
+ * Apply background color to a line, padding to full width.
+ *
+ * @param line - Line of text (may contain ANSI codes)
+ * @param width - Total width to pad to
+ * @param bgFn - Background color function
+ * @returns Line with background applied and padded to width
+ */
+export declare function applyBackgroundToLine(line: string, width: number, bgFn: (text: string) => string): string;
+/**
+ * Extract a range of visible columns from a line. Handles ANSI codes and wide chars.
+ *
+ * @param strict - If true, exclude wide chars at boundary that would extend past the range
+ */
+export declare function sliceByColumn(line: string, startCol: number, length: number, strict?: boolean): string;

package/package.json

@@ -1,9 +1,9 @@
 {
 	"type": "module",
 	"name": "@sayknow-cli/tui",
-	"version": "0.3.6",
+	"version": "0.3.8",
 	"description": "Terminal User Interface library with differential rendering for efficient text-based applications",
-	"homepage": "https://github.com/jaybeyond/Sayknow_CLI",
+	"homepage": "https://sayknow-cli.com",
 	"author": "jaybeyond",
 	"contributors": [
 		"Mario Zechner"
@@ -27,7 +27,7 @@
 		"cli"
 	],
 	"main": "./src/index.ts",
-	"types": "./src/index.ts",
+	"types": "./dist/types/index.d.ts",
 	"scripts": {
 		"check": "biome check . && bun run check:types",
 		"check:types": "tsgo -p tsconfig.json --noEmit",
@@ -38,8 +38,8 @@
 		"fmt": "biome format --write ."
 	},
 	"dependencies": {
-		"@sayknow-cli/natives": "0.3.6",
-		"@sayknow-cli/utils": "0.3.6",
+		"@sayknow-cli/natives": "0.3.8",
+		"@sayknow-cli/utils": "0.3.8",
 		"lru-cache": "11.3.6",
 		"marked": "^18.0.3"
 	},
@@ -53,19 +53,20 @@
 	"files": [
 		"src",
 		"README.md",
-		"CHANGELOG.md"
+		"CHANGELOG.md",
+		"dist/types"
 	],
 	"exports": {
 		".": {
-			"types": "./src/index.ts",
+			"types": "./dist/types/index.d.ts",
 			"import": "./src/index.ts"
 		},
 		"./*": {
-			"types": "./src/*.ts",
+			"types": "./dist/types/*.d.ts",
 			"import": "./src/*.ts"
 		},
 		"./components/*": {
-			"types": "./src/components/*.ts",
+			"types": "./dist/types/components/*.d.ts",
 			"import": "./src/components/*.ts"
 		},
 		"./*.js": "./src/*.ts"

package/src/animation-scheduler.ts

@@ -0,0 +1,99 @@
+export type AnimationCadence = 16 | 80;
+
+type TimerHandle = ReturnType<typeof setInterval>;
+type AnimationCallback = (now: number) => void;
+
+interface CadenceBucket {
+	callbacks: Set<AnimationCallback>;
+	timer?: TimerHandle;
+	startedTimers: number;
+}
+
+const buckets = new Map<AnimationCadence, CadenceBucket>();
+
+function getBucket(cadence: AnimationCadence): CadenceBucket {
+	let bucket = buckets.get(cadence);
+	if (!bucket) {
+		bucket = { callbacks: new Set(), startedTimers: 0 };
+		buckets.set(cadence, bucket);
+	}
+	return bucket;
+}
+
+function startBucket(cadence: AnimationCadence, bucket: CadenceBucket): void {
+	if (bucket.timer) return;
+	bucket.timer = setInterval(() => {
+		const now = performance.now();
+		// Snapshot so re-entrant register/unregister during a tick is safe, and
+		// isolate each callback so one throwing registrant cannot starve siblings
+		// or surface as an uncaught exception that kills the shared timer.
+		for (const callback of [...bucket.callbacks]) {
+			try {
+				callback(now);
+			} catch (err) {
+				console.error("[animation-scheduler] callback threw:", err);
+			}
+		}
+	}, cadence);
+	bucket.startedTimers += 1;
+	bucket.timer?.unref?.();
+}
+
+function stopBucket(bucket: CadenceBucket): void {
+	if (!bucket.timer) return;
+	clearInterval(bucket.timer);
+	bucket.timer = undefined;
+}
+
+export interface AnimationRegistration {
+	unregister(): void;
+}
+
+export function registerAnimationCallback(
+	callback: AnimationCallback,
+	cadence: AnimationCadence = 80,
+): AnimationRegistration {
+	const bucket = getBucket(cadence);
+	bucket.callbacks.add(callback);
+	startBucket(cadence, bucket);
+	let registered = true;
+
+	return {
+		unregister(): void {
+			if (!registered) return;
+			registered = false;
+			bucket.callbacks.delete(callback);
+			if (bucket.callbacks.size === 0) stopBucket(bucket);
+		},
+	};
+}
+
+export const __animationSchedulerTestHooks = {
+	getActiveTimerCount(cadence?: AnimationCadence): number {
+		if (cadence !== undefined) return getBucket(cadence).timer ? 1 : 0;
+		let count = 0;
+		for (const bucket of buckets.values()) {
+			if (bucket.timer) count += 1;
+		}
+		return count;
+	},
+	getRegistrantCount(cadence?: AnimationCadence): number {
+		if (cadence !== undefined) return getBucket(cadence).callbacks.size;
+		let count = 0;
+		for (const bucket of buckets.values()) count += bucket.callbacks.size;
+		return count;
+	},
+	getStartedTimerCount(cadence?: AnimationCadence): number {
+		if (cadence !== undefined) return getBucket(cadence).startedTimers;
+		let count = 0;
+		for (const bucket of buckets.values()) count += bucket.startedTimers;
+		return count;
+	},
+	reset(): void {
+		for (const bucket of buckets.values()) {
+			stopBucket(bucket);
+			bucket.callbacks.clear();
+			bucket.startedTimers = 0;
+		}
+	},
+};