@utsp/runtime-client 0.11.0 → 0.12.0

package/dist/index.d.ts

@@ -1,9 +1,704 @@
+import { Core, User, AnyPostProcessOrder } from '@utsp/core';
+import { IApplication, IRenderer } from '@utsp/types';
+export { IApplication } from '@utsp/types';
 import { AutoplayOverlayOptions, PostProcessOverlay } from '@utsp/render';
 export { ScalingMode } from '@utsp/render';
 import { AudioManager } from '@utsp/audio';
 export { AudioManager, AudioManagerOptions, ToneOptions } from '@utsp/audio';
-import { IApplication, ScalingMode } from '@utsp/types';
-export { IApplication } from '@utsp/types';
+import * as _utsp_input from '@utsp/input';
+import { UnifiedInputRouter, MobileVibration } from '@utsp/input';
+
+/**
+ * Base Runtime Types
+ *
+ * Types shared by all client runtime variants (Micro, Mini, Standard)
+ */
+
+/**
+ * Renderer type to use
+ */
+declare enum RendererType {
+    /** WebGL2 renderer - Optimized WebGL 1.0 with GPU palette, instanced rendering (default, recommended) */
+    TerminalGL = "webgl",
+    /** Canvas 2D renderer - CPU fallback with ImageData optimization for benchmarks */
+    Terminal2D = "terminal2d"
+}
+/**
+ * Render mode for runtimes
+ */
+type RenderMode = 
+/** Continuous rendering at max FPS (default) - requestAnimationFrame loop */
+'continuous'
+/** On-demand rendering - only renders when explicitly requested via requestRender() */
+ | 'on-demand';
+/**
+ * Base options shared by all client runtime variants
+ */
+interface BaseRuntimeOptions {
+    /** Application instance */
+    application: IApplication;
+    /** Container HTML element for rendering */
+    container: HTMLElement;
+    /** Enable debug logging */
+    debug?: boolean;
+    /** Initial display width in columns (default: 80). Can be overridden by IApplication via Display */
+    width?: number;
+    /** Initial display height in rows (default: 25). Can be overridden by IApplication via Display */
+    height?: number;
+    /** Renderer type (default: TerminalGL) */
+    renderer?: RendererType;
+    /** Enable ImageData rendering for Canvas 2D (default: true). */
+    useImageDataRendering?: boolean;
+    /** Render mode: 'continuous' (default) or 'on-demand' */
+    renderMode?: RenderMode;
+}
+/**
+ * Performance timing for a single frame
+ */
+interface FrameTiming$1 {
+    /** Time spent in Core tick (ms) */
+    coreTime: number;
+    /** Time spent in Renderer (ms) */
+    renderTime: number;
+    /** Total frame time (ms) */
+    totalTime: number;
+}
+/**
+ * Base runtime statistics
+ */
+interface BaseRuntimeStats {
+    /** Is runtime currently running */
+    running: boolean;
+    /** Number of users */
+    userCount: number;
+    /** Current FPS */
+    fps: number;
+    /** Uptime in milliseconds */
+    uptime: number;
+    /** Total frames processed */
+    totalFrames: number;
+    /** Last frame timing breakdown */
+    lastFrameTiming?: FrameTiming$1;
+    /** Average frame timing over last 60 frames */
+    avgFrameTiming?: FrameTiming$1;
+}
+
+/**
+ * Performance Monitor
+ *
+ * Tracks and monitors runtime performance metrics including FPS,
+ * frame timing, and rolling averages.
+ *
+ * This class is responsible for:
+ * - FPS calculation and tracking
+ * - Frame timing measurements (core, render, total)
+ * - Rolling averages over configurable sample size
+ * - Performance statistics reporting
+ *
+ * @example
+ * ```typescript
+ * const monitor = new PerformanceMonitor(60); // 60 sample rolling average
+ *
+ * // In initialization
+ * monitor.startTracking(performance.now());
+ *
+ * // Every frame
+ * monitor.updateFPS(timestamp);
+ *
+ * // After frame work
+ * monitor.recordFrameTiming(coreTime, renderTime);
+ *
+ * // Get metrics
+ * const stats = monitor.getStats();
+ * console.log(`FPS: ${stats.fps}, Avg Frame Time: ${stats.avgTotalTime}ms`);
+ * ```
+ */
+/**
+ * Frame timing data for a single frame
+ */
+interface FrameTiming {
+    /** Time spent in core logic (ms) */
+    coreTime: number;
+    /** Time spent in rendering (ms) */
+    renderTime: number;
+    /** Total frame time (ms) */
+    totalTime: number;
+}
+/**
+ * Performance statistics summary
+ */
+interface PerformanceStats {
+    /** Current frames per second */
+    fps: number;
+    /** Last recorded frame timing */
+    lastFrame?: FrameTiming;
+    /** Average frame timing over sample window */
+    avgFrame?: FrameTiming;
+    /** Number of samples in rolling average */
+    sampleCount: number;
+    /** Maximum sample size */
+    maxSamples: number;
+}
+/**
+ * Monitors and tracks runtime performance metrics
+ *
+ * Provides FPS tracking, frame timing measurements, and rolling averages
+ * for performance analysis and optimization.
+ */
+declare class PerformanceMonitor {
+    private frameCount;
+    private fps;
+    private fpsUpdateTime;
+    private lastCoreTime;
+    private lastRenderTime;
+    private lastTotalTime;
+    private coreTimeSamples;
+    private renderTimeSamples;
+    private totalTimeSamples;
+    private readonly maxSamples;
+    /**
+     * Creates a new PerformanceMonitor
+     *
+     * @param maxSamples - Maximum number of samples to keep for rolling averages (default: 60)
+     *
+     * @example
+     * ```typescript
+     * const monitor = new PerformanceMonitor(60); // Track last 60 frames
+     * ```
+     */
+    constructor(maxSamples?: number);
+    /**
+     * Start FPS tracking
+     *
+     * Call this once when starting performance monitoring.
+     * Initializes the FPS calculation baseline.
+     *
+     * @param timestamp - Initial timestamp from performance.now()
+     *
+     * @example
+     * ```typescript
+     * monitor.startTracking(performance.now());
+     * ```
+     */
+    startTracking(timestamp: number): void;
+    /**
+     * Update frame counter and calculate FPS
+     *
+     * Call this every frame in your main loop. Automatically calculates
+     * FPS every second based on frame count.
+     *
+     * @param timestamp - Current timestamp from performance.now()
+     *
+     * @example
+     * ```typescript
+     * function mainLoop(timestamp: number) {
+     *   monitor.updateFPS(timestamp);
+     *   // ... rest of frame logic
+     * }
+     * ```
+     */
+    updateFPS(timestamp: number): void;
+    /**
+     * Record frame timing for the current frame
+     *
+     * Call this after each frame completes to record timing data.
+     * Maintains a rolling window of samples for average calculation.
+     *
+     * @param coreTime - Time spent in core logic (ms)
+     * @param renderTime - Time spent in rendering (ms)
+     *
+     * @example
+     * ```typescript
+     * const coreStart = performance.now();
+     * // ... core logic
+     * const coreTime = performance.now() - coreStart;
+     *
+     * const renderStart = performance.now();
+     * // ... rendering
+     * const renderTime = performance.now() - renderStart;
+     *
+     * monitor.recordFrameTiming(coreTime, renderTime);
+     * ```
+     */
+    recordFrameTiming(coreTime: number, renderTime: number): void;
+    /**
+     * Get current FPS
+     *
+     * @returns Current frames per second
+     *
+     * @example
+     * ```typescript
+     * console.log(`FPS: ${monitor.getFPS()}`);
+     * ```
+     */
+    getFPS(): number;
+    /**
+     * Get last recorded frame timing
+     *
+     * Returns undefined if no frames have been recorded yet.
+     *
+     * @returns Last frame timing or undefined
+     *
+     * @example
+     * ```typescript
+     * const last = monitor.getLastFrameTiming();
+     * if (last) {
+     *   console.log(`Last frame: ${last.totalTime.toFixed(2)}ms`);
+     * }
+     * ```
+     */
+    getLastFrameTiming(): FrameTiming | undefined;
+    /**
+     * Get average frame timing over sample window
+     *
+     * Returns undefined if no samples have been recorded yet.
+     *
+     * @returns Average frame timing or undefined
+     *
+     * @example
+     * ```typescript
+     * const avg = monitor.getAverageFrameTiming();
+     * if (avg) {
+     *   console.log(`Avg frame: ${avg.totalTime.toFixed(2)}ms`);
+     *   console.log(`Avg core: ${avg.coreTime.toFixed(2)}ms`);
+     *   console.log(`Avg render: ${avg.renderTime.toFixed(2)}ms`);
+     * }
+     * ```
+     */
+    getAverageFrameTiming(): FrameTiming | undefined;
+    /**
+     * Get comprehensive performance statistics
+     *
+     * Returns all available performance metrics including FPS,
+     * last frame timing, average timing, and sample counts.
+     *
+     * @returns Performance statistics
+     *
+     * @example
+     * ```typescript
+     * const stats = monitor.getStats();
+     * console.log(`FPS: ${stats.fps}`);
+     * console.log(`Samples: ${stats.sampleCount}/${stats.maxSamples}`);
+     * if (stats.avgFrame) {
+     *   console.log(`Avg Frame Time: ${stats.avgFrame.totalTime.toFixed(2)}ms`);
+     * }
+     * ```
+     */
+    getStats(): PerformanceStats;
+    /**
+     * Reset all performance data
+     *
+     * Clears all tracked metrics and samples. Useful for restarting
+     * performance monitoring without creating a new instance.
+     *
+     * @example
+     * ```typescript
+     * monitor.reset();
+     * monitor.startTracking(performance.now());
+     * ```
+     */
+    reset(): void;
+    /**
+     * Calculate average of an array of numbers
+     *
+     * @param arr - Array of numbers
+     * @returns Average value
+     * @private
+     */
+    private average;
+}
+
+/**
+ * Renderer Manager
+ *
+ * Manages renderer lifecycle including initialization, font loading,
+ * readiness checks, and rendering operations.
+ *
+ * This class is responsible for:
+ * - Renderer readiness waiting (async initialization)
+ * - Default font loading and registration
+ * - Rendering operation delegation
+ * - Renderer cleanup and destruction
+ *
+ * @example
+ * ```typescript
+ * const manager = new RendererManager(renderer, {
+ *   debug: true,
+ *   useImageDataRendering: false
+ * });
+ *
+ * // Initialize
+ * await manager.initialize(core);
+ *
+ * // Render
+ * manager.render(userId);
+ *
+ * // Cleanup
+ * manager.destroy();
+ * ```
+ */
+
+/**
+ * Configuration options for RendererManager
+ */
+interface RendererManagerOptions {
+    /** Enable debug logging */
+    debug?: boolean;
+    /** Enable ImageData rendering optimization (Terminal2D only) */
+    useImageDataRendering?: boolean;
+}
+/**
+ * Browser-specific renderer interface
+ * Refines IRenderer's getCanvas() return type from unknown to HTMLCanvasElement
+ * and adds optional Terminal2D-specific methods
+ */
+type ConcreteRenderer = IRenderer & {
+    /**
+     * Get canvas element (browser-specific)
+     * Refines the return type from unknown to HTMLCanvasElement | null
+     */
+    getCanvas(): HTMLCanvasElement | null;
+    /**
+     * Enable ImageData rendering optimization (Terminal2D specific, optional)
+     */
+    setImageDataRendering?: (enabled: boolean) => void;
+};
+/**
+ * Manages renderer lifecycle and operations
+ *
+ * Provides abstraction layer for renderer initialization, font loading,
+ * and rendering operations. Handles differences between renderer types
+ * (e.g., async WebGL initialization vs instant Canvas2D).
+ */
+declare class RendererManager {
+    private renderer;
+    private options;
+    /**
+     * Creates a new RendererManager
+     *
+     * @param renderer - Renderer instance to manage
+     * @param options - Configuration options
+     *
+     * @example
+     * ```typescript
+     * const renderer = new TerminalGL(container, width, height);
+     * const manager = new RendererManager(renderer, { debug: true });
+     * ```
+     */
+    constructor(renderer: ConcreteRenderer, options?: RendererManagerOptions);
+    /**
+     * Initialize renderer (wait for ready + load default font)
+     *
+     * Call this before using the renderer. Handles async initialization
+     * for WebGL renderers and loads the default ASCII 8x8 font atlas.
+     *
+     * @param core - Core instance for font registry access
+     * @throws Error if renderer fails to be ready after timeout
+     *
+     * @example
+     * ```typescript
+     * await manager.initialize(core);
+     * // Renderer is now ready and font is loaded
+     * ```
+     */
+    initialize(_core: Core): Promise<void>;
+    /**
+     * Wait for renderer to be ready
+     *
+     * Some renderers (WebGL) require async initialization. This method
+     * polls isReady() until the renderer is ready or timeout occurs.
+     *
+     * @param maxAttempts - Maximum polling attempts (default: 100)
+     * @param intervalMs - Polling interval in milliseconds (default: 50ms)
+     * @throws Error if renderer fails to be ready after maxAttempts
+     *
+     * @example
+     * ```typescript
+     * await manager.waitForReady();
+     * console.log('Renderer is ready!');
+     * ```
+     */
+    waitForReady(maxAttempts?: number, intervalMs?: number): Promise<void>;
+    /**
+     * @deprecated Default 8x8 font is no longer used. Use ImageFont instead.
+     * This method is kept for backwards compatibility but does nothing.
+     */
+    loadDefaultFont(_core: Core): Promise<void>;
+    /**
+     * Render display data for a specific user
+     *
+     * Retrieves render state from core and renders the first display.
+     * Checks renderer readiness before rendering.
+     *
+     * @param core - Core instance for render state access
+     * @param userId - User ID to render for
+     * @returns true if rendering succeeded, false otherwise
+     *
+     * @example
+     * ```typescript
+     * const rendered = manager.render(core, userId);
+     * if (!rendered) {
+     *   console.warn('Rendering failed or skipped');
+     * }
+     * ```
+     */
+    render(core: Core, userId: string): boolean;
+    /**
+     * Get the underlying renderer instance
+     *
+     * @returns Renderer instance
+     *
+     * @example
+     * ```typescript
+     * const renderer = manager.getRenderer();
+     * const canvas = renderer.getCanvas();
+     * ```
+     */
+    getRenderer(): ConcreteRenderer;
+    /**
+     * Get renderer canvas element
+     *
+     * Convenience method to access the renderer's canvas.
+     *
+     * @returns Canvas element or null if not available
+     *
+     * @example
+     * ```typescript
+     * const canvas = manager.getCanvas();
+     * if (canvas) {
+     *   canvas.addEventListener('click', handleClick);
+     * }
+     * ```
+     */
+    getCanvas(): HTMLCanvasElement | null;
+    /**
+     * Check if renderer is ready
+     *
+     * @returns true if renderer is ready to render
+     *
+     * @example
+     * ```typescript
+     * if (manager.isReady()) {
+     *   manager.render(core, userId);
+     * }
+     * ```
+     */
+    isReady(): boolean;
+    /**
+     * Destroy renderer and cleanup resources
+     *
+     * Delegates to the underlying renderer's destroy method.
+     * Should be called when the renderer is no longer needed.
+     *
+     * @example
+     * ```typescript
+     * manager.destroy();
+     * console.log('Renderer destroyed');
+     * ```
+     */
+    destroy(): void;
+    /**
+     * Log debug message if debug mode is enabled
+     *
+     * @param message - Message to log
+     * @private
+     */
+    private log;
+}
+
+/**
+ * Base Client Runtime
+ *
+ * Abstract base class for all client runtime variants.
+ * Provides core functionality: rendering, core management, and lifecycle.
+ *
+ * Features NOT included (handled by subclasses):
+ * - Input handling
+ * - Audio
+ * - Network
+ * - Post-processing effects
+ * - Autoplay overlay
+ */
+
+/**
+ * Abstract base class for all client runtimes
+ */
+declare abstract class BaseClientRuntime {
+    /** Core instance managing application state */
+    protected core: Core;
+    /** Renderer manager wrapping the actual renderer */
+    protected rendererManager: RendererManager;
+    /** Current renderer type */
+    protected rendererType: RendererType;
+    /** Normalized options with defaults applied */
+    protected options: Required<BaseRuntimeOptions>;
+    /** Is the runtime currently running */
+    protected running: boolean;
+    /** Timestamp when runtime started */
+    protected startTime: number;
+    /** Last frame timestamp */
+    protected lastTimestamp: number;
+    /** Current user ID */
+    protected userId: string;
+    /** Visibility change handler for tab switching */
+    protected visibilityChangeHandler?: () => void;
+    /** Tick rate in TPS (0 = no updates) */
+    protected tickRate: number;
+    /** Accumulated time for fixed timestep */
+    protected accumulatedTime: number;
+    /** Minimum frame time (1000/maxFPS) */
+    protected readonly FRAME_TIME_MIN: number;
+    /** Last render timestamp for frame limiting */
+    protected lastRenderTimestamp: number;
+    /** requestAnimationFrame ID */
+    protected rafId: number;
+    /** Flag to prevent catch-up ticks on first frame */
+    protected firstTickDone: boolean;
+    /** Performance monitoring */
+    protected performanceMonitor: PerformanceMonitor;
+    /** Render mode: continuous or on-demand */
+    protected renderMode: 'continuous' | 'on-demand';
+    /** Flag for on-demand render requests */
+    protected renderRequested: boolean;
+    constructor(options: BaseRuntimeOptions);
+    /**
+     * Create the appropriate renderer based on options
+     */
+    protected createRenderer(): ConcreteRenderer;
+    /**
+     * Get the renderer type
+     */
+    getRendererType(): RendererType;
+    /**
+     * Check if runtime is running
+     */
+    isRunning(): boolean;
+    /**
+     * Set the tick rate (TPS)
+     */
+    setTickRate(tickRate: number): void;
+    /**
+     * Set render mode
+     */
+    setRenderMode(mode: 'continuous' | 'on-demand'): void;
+    /**
+     * Set maximum FPS
+     */
+    setMaxFPS(fps: number): void;
+    /**
+     * Get current tick rate
+     */
+    getTickRate(): number;
+    /**
+     * Request a render in on-demand mode
+     */
+    requestRender(): void;
+    /**
+     * Start the runtime
+     */
+    start(): Promise<void>;
+    /**
+     * Hook called before start() initializes renderer
+     * Override in subclasses to handle autoplay, audio initialization, etc.
+     */
+    protected onBeforeStart(): Promise<void>;
+    /**
+     * Hook called after application.init() but before createLocalUser()
+     * Override in subclasses to configure input targets, etc.
+     */
+    protected onAfterInit(): Promise<void>;
+    /**
+     * Stop the runtime
+     */
+    stop(): Promise<void>;
+    /**
+     * Hook called during stop() for subclass cleanup
+     */
+    protected onStop(): Promise<void>;
+    /**
+     * Get runtime statistics
+     */
+    getStats(): BaseRuntimeStats;
+    /**
+     * Destroy the runtime and clean up all resources
+     */
+    destroy(): Promise<void>;
+    /**
+     * Hook called during destroy() for subclass cleanup
+     */
+    protected onDestroy(): Promise<void>;
+    /**
+     * Create a local user
+     */
+    protected createLocalUser(): Promise<void>;
+    /**
+     * Hook called when user is created, before initUser()
+     * Override to inject audio processor, vibration, etc.
+     */
+    protected onUserCreated(_user: User): void;
+    /**
+     * Process initial orders after initUser()
+     * Override to handle macro orders, post-process, etc.
+     */
+    protected processInitialOrders(user: User): void;
+    /**
+     * Main game loop
+     */
+    protected mainLoop(timestamp: number): void;
+    /**
+     * Collect and apply input from devices
+     * Override in subclasses with input support
+     */
+    protected collectAndApplyInput(_user: User): void;
+    /**
+     * Process orders generated during tick (sounds, vibration, etc.)
+     * Override in subclasses with audio/postprocess support
+     */
+    protected processTickOrders(user: User): void;
+    /**
+     * Render the current state
+     */
+    protected render(): void;
+    /**
+     * Handle palette change from Core
+     */
+    protected onCorePaletteChanged(palette: Map<number, {
+        r: number;
+        g: number;
+        b: number;
+        a: number;
+        e: number;
+    }>): void;
+    /**
+     * Handle bitmap font change from Core
+     */
+    protected onCoreBitmapFontChanged(fontId: number): void;
+    /**
+     * Handle image font change from Core
+     */
+    protected onCoreImageFontChanged(fontId: number): void;
+    /**
+     * Hook called after font change for post-process sync
+     * Override in subclasses with post-process support
+     */
+    protected onFontChanged(_renderer: ConcreteRenderer): void;
+    /**
+     * Debug logging
+     */
+    protected log(message: string): void;
+    /**
+     * Get the Core instance
+     */
+    getCore(): Core;
+    /**
+     * Get the renderer manager
+     */
+    getRendererManager(): RendererManager;
+    /**
+     * Get current user ID
+     */
+    getUserId(): string;
+}
 
 /**
  * Runtime Client Types and Options
@@ -13,23 +708,6 @@ export { IApplication } from '@utsp/types';
  * Client runtime mode
  */
 type ClientRuntimeMode = 'local' | 'connected';
-/**
- * Renderer type to use
- */
-declare enum RendererType {
-    /** WebGL2 renderer - Optimized WebGL 1.0 with GPU palette, instanced rendering (default, recommended) */
-    TerminalGL = "webgl",
-    /** Canvas 2D renderer - CPU fallback with ImageData optimization for benchmarks */
-    Terminal2D = "terminal2d"
-}
-/**
- * Render mode for ClientRuntime
- */
-type RenderMode = 
-/** Continuous rendering at max FPS (default) - requestAnimationFrame loop */
-'continuous'
-/** On-demand rendering - only renders when explicitly requested via requestRender() */
- | 'on-demand';
 /**
  * Base client runtime options
  */
@@ -57,23 +735,8 @@ interface BaseClientRuntimeOptions {
     };
     /** Enable ImageData rendering for Canvas 2D (default: true). Provides pixel-perfect rendering with no gaps between cells. 10-20× faster than fillRect. Only for Terminal2D renderer with bitmap fonts. */
     useImageDataRendering?: boolean;
-    /** Render mode: 'continuous' (default) renders at max FPS, 'on-demand' only renders when explicitly requested. When tickRate is 0, automatically switches to 'on-demand'. */
+    /** Render mode: 'continuous' (default) renders at max FPS, 'on-demand' only renders when explicitly requested. */
     renderMode?: RenderMode;
-    /** Tick rate in ticks per second (default: 30). Set to 0 to disable update loop (only init/initUser, no update/updateUser). When set to 0, automatically enables 'on-demand' render mode. */
-    tickRate?: number;
-    /**
-     * Scaling mode for pixel-perfect rendering (default: ScalingMode.None)
-     *
-     * Controls how the canvas is scaled to fit the container:
-     * - ScalingMode.None: Fills available space, may have sub-pixel artifacts (default)
-     * - ScalingMode.Eighth: Snaps to 0.125 increments (1.0, 1.125, 1.25...)
-     * - ScalingMode.Quarter: Snaps to 0.25 increments (1.0, 1.25, 1.5...)
-     * - ScalingMode.Half: Snaps to 0.5 increments (1.0, 1.5, 2.0...)
-     * - ScalingMode.Integer: Integer scaling only (1x, 2x, 3x...), crispest pixels
-     *
-     * Use ScalingMode.Integer for pixel-art style games that need crisp, artifact-free rendering.
-     */
-    scalingMode?: ScalingMode;
     /** Capture input events to prevent default browser behavior (Tab, arrows, etc.). Default: false. When true, preventDefault() and stopPropagation() are called on keyboard and mouse events to keep focus in the terminal. All F keys (F1-F12) and Ctrl/Cmd shortcuts are automatically excluded. */
     captureInput?: boolean;
     /** Enable input handling (keyboard, mouse, touch, gamepad). Default: true. When false, no input listeners are created - useful for display-only clients in documentation pages where you want to scroll freely without the client intercepting events. */
@@ -140,17 +803,6 @@ interface ConnectedModeOptions extends BaseClientRuntimeOptions {
  * Union type of client runtime options
  */
 type ClientRuntimeOptions = LocalModeOptions | ConnectedModeOptions;
-/**
- * Performance timing for a single frame
- */
-interface FrameTiming {
-    /** Time spent in Core tick (ms) */
-    coreTime: number;
-    /** Time spent in Renderer (ms) */
-    renderTime: number;
-    /** Total frame time (ms) */
-    totalTime: number;
-}
 /**
  * Client runtime statistics
  */
@@ -170,39 +822,29 @@ interface ClientRuntimeStats {
     /** Network latency in ms (connected mode only) */
     latency?: number;
     /** Last frame timing breakdown */
-    lastFrameTiming?: FrameTiming;
+    lastFrameTiming?: FrameTiming$1;
     /** Average frame timing over last 60 frames */
-    avgFrameTiming?: FrameTiming;
+    avgFrameTiming?: FrameTiming$1;
 }
 
 /**
- * Client Runtime
+ * Client Runtime (Standard)
  *
- * Unified client runtime supporting both local and connected modes.
+ * Full-featured client runtime supporting both local and connected modes.
+ * Extends BaseClientRuntime with:
+ * - Input handling (keyboard, mouse, touch, gamepad)
+ * - Audio support
+ * - Network synchronization
+ * - Post-processing effects
+ * - Autoplay overlay
+ * - Bridge messaging
  */
 
-declare class ClientRuntime {
-    private core;
-    private rendererManager;
-    private rendererType;
+declare class ClientRuntime extends BaseClientRuntime {
     private input;
     private networkSync;
-    private options;
-    private running;
-    private startTime;
-    private lastTimestamp;
-    private userId;
     private mode;
-    private visibilityChangeHandler?;
-    private tickRate;
-    private accumulatedTime;
-    private readonly FRAME_TIME_MIN;
-    private lastRenderTimestamp;
-    private rafId;
-    private firstTickDone;
-    private performanceMonitor;
-    private renderMode;
-    private renderRequested;
+    private localOptions;
     private autoplayOverlay;
     private autoplay;
     private audioManager;
@@ -213,221 +855,239 @@ declare class ClientRuntime {
     private localBridgeWildcardHandlers;
     constructor(options: ClientRuntimeOptions);
     getMode(): ClientRuntimeMode;
-    getRendererType(): RendererType;
-    isRunning(): boolean;
-    private createRenderer;
     setTickRate(tickRate: number): void;
-    setRenderMode(mode: 'continuous' | 'on-demand'): void;
-    setMaxFPS(fps: number): void;
-    getTickRate(): number;
     /**
-     * Request a render in on-demand mode.
-     * Has no effect in continuous mode (renders automatically).
-     *
-     * @example
-     * ```typescript
-     * // On-demand mode: render only when needed
-     * const runtime = new ClientRuntime({
-     *   mode: 'local',
-     *   renderMode: 'on-demand',
-     *   tickRate: 0, // Disable update loop
-     *   application: myApp,
-     *   container: document.getElementById('app')
-     * });
-     *
-     * await runtime.start();
-     *
-     * // Manually request render after changing something
-     * core.getUser('local').setCell(0, 0, '@', 1, 0);
-     * runtime.requestRender(); // Trigger render
-     * ```
+     * Override onBeforeStart to handle autoplay and audio initialization
+     */
+    protected onBeforeStart(): Promise<void>;
+    /**
+     * Override onAfterInit to configure input and post-process
+     */
+    protected onAfterInit(): Promise<void>;
+    /**
+     * Override start() for connected mode
      */
-    requestRender(): void;
     start(): Promise<void>;
-    stop(): Promise<void>;
+    /**
+     * Override onStop for cleanup
+     */
+    protected onStop(): Promise<void>;
     getStats(): ClientRuntimeStats;
-    destroy(): Promise<void>;
-    private createLocalUser;
+    /**
+     * Override onDestroy for full cleanup
+     */
+    protected onDestroy(): Promise<void>;
+    /**
+     * Override createLocalUser for full feature support
+     */
+    protected createLocalUser(): Promise<void>;
     /**
      * Load sounds from Core's SoundRegistry into AudioManager's SoundBank
-     * Used in standalone mode to transfer sounds registered via core.loadSound()
-     * @private
      */
     private loadSoundsFromRegistry;
-    private mainLoop;
-    private collectAndApplyInput;
-    private collectAndSendInput;
-    private render;
     /**
-     * Handle palette change from Core
-     * Converts Core palette Map to RGBColor array and updates renderer
+     * Override mainLoop for connected mode support
      */
-    private onCorePaletteChanged;
+    protected mainLoop(timestamp: number): void;
     /**
-     * Handle bitmap font change from Core
-     * Loads the font from registry and updates renderer
+     * Override collectAndApplyInput for full input support
      */
-    private onCoreBitmapFontChanged;
+    protected collectAndApplyInput(user: User): void;
+    private collectAndSendInput;
     /**
-     * Handle image font change from Core
-     * Loads the PNG font atlas from registry and updates renderer
+     * Override onFontChanged to sync PostProcessOverlay
      */
-    private onCoreImageFontChanged;
+    protected onFontChanged(renderer: ConcreteRenderer): void;
     /**
      * Get the AudioManager instance
-     * Returns null before start() is called
      */
     getAudioManager(): InstanceType<typeof AudioManager> | null;
     /**
-     * Get the AudioContext instance (convenience method)
-     * Returns null if AudioManager not initialized
+     * Get the AudioContext instance
      */
     getAudioContext(): AudioContext | null;
     /**
-     * Apply ambient effect configuration to the TerminalGL renderer
+     * Get the PostProcessOverlay instance
+     */
+    getPostProcessOverlay(): PostProcessOverlay | null;
+    /**
+     * Apply ambient effect configuration
      */
     private applyAmbientEffectConfig;
     /**
-     * Apply post-process orders received from the network
-     * These are binary orders decoded from UpdatePacket
+     * Apply post-process orders
      */
     private applyPostProcessOrders;
+    private applyScalingMode;
+    private applyGridConfig;
+    private patternFromType;
+    private dispatchLocalBridgeMessages;
+    sendBridge(channel: string, data: unknown): void;
+    onBridge<T = unknown>(channel: string, handler: (data: T) => void): void;
+    offBridge<T = unknown>(channel: string, handler: (data: T) => void): void;
+    removeAllBridgeHandlers(channel?: string): void;
     /**
-     * Apply scaling mode from order
+     * Override log for mode-specific prefix
      */
-    private applyScalingMode;
+    protected log(message: string): void;
+}
+
+interface InputFeatureOptions {
+    debug?: boolean;
+    captureInput?: boolean;
+    mobileInputConfig?: {
+        preventDefault?: boolean;
+        passive?: boolean;
+        maxTouches?: number;
+    };
+}
+declare class InputFeature {
+    private input;
+    private mobileVibration;
+    constructor(options?: InputFeatureOptions);
     /**
-     * Apply grid configuration from order
+     * Set mobile input target (usually the canvas)
      */
-    private applyGridConfig;
+    setMobileTarget(element: HTMLElement): void;
     /**
-     * Convert ScanlinesPatternType enum to string pattern
+     * Start listening for input
      */
-    private patternFromType;
+    start(): void;
     /**
-     * Get the PostProcessOverlay instance
-     * Returns null before start() is called
+     * Stop listening for input
      */
-    getPostProcessOverlay(): PostProcessOverlay | null;
+    stop(): void;
     /**
-     * Send a bridge message to the server
-     *
-     * Bridge messages bypass the UTSP protocol and allow direct communication
-     * with the server application. Use this for external UI communication
-     * (chat, settings, custom commands, etc.).
-     *
-     * **Note:** Only available in 'connected' mode. In 'local' mode, this is a no-op.
-     *
-     * @param channel - Channel name (e.g., 'chat', 'settings', 'ready')
-     * @param data - Any JSON-serializable data
-     *
-     * @example
-     * ```typescript
-     * // Send a chat message
-     * runtime.sendBridge('chat', { message: 'Hello everyone!' });
-     *
+     * Destroy and cleanup
+     */
+    destroy(): void;
     /**
-     * Dispatch bridge messages from application to local handlers
-     *
-     * In local mode, this simulates the server→client path by calling
-     * registered handlers directly. Same timing as connected mode.
-     *
-     * @param messages - Array of bridge messages from user.getBridgeMessages()
-     * @private
+     * Get the input router (for network sync)
      */
-    private dispatchLocalBridgeMessages;
+    getRouter(): UnifiedInputRouter;
     /**
-     * Send a message to the server via the bridge channel
-     *
-     * Bridge messages are sent immediately (not queued), bypassing the UTSP
-     * protocol for real-time external app communication.
-     *
-     * **Note:** In 'connected' mode, sends to server. In 'local' mode, routes
-     * directly to application.onBridgeMessage for isomorphic behavior.
-     *
-     * @param channel - Channel name (e.g., 'chat', 'ready', 'settings')
-     * @param data - Data to send (will be JSON serialized)
-     *
-     * @example
-     * ```typescript
-     * // Send a chat message
-     * runtime.sendBridge('chat', { message: 'Hello everyone!' });
-     *
-     * // Mark player as ready
-     * runtime.sendBridge('ready', { ready: true });
-     *
-     * // Send custom settings
-     * runtime.sendBridge('settings', { volume: 0.8, theme: 'dark' });
-     * ```
+     * Get gamepad for vibration processor injection
      */
-    sendBridge(channel: string, data: unknown): void;
+    getGamepad(): _utsp_input.GamepadInputs | null;
     /**
-     * Register a handler for incoming bridge messages from the application
-     *
-     * Bridge messages from the application (via user.sendBridge) are synchronized
-     * with tick updates, arriving at the same time as render updates for consistency.
-     *
-     * **Isomorphic:** Works in both 'connected' and 'local' modes.
-     * - Connected: Messages come from server via network
-     * - Local: Messages are dispatched directly from application
-     *
-     * @param channel - Channel name to listen for (use '*' for all channels)
-     * @param handler - Callback function receiving the parsed data
-     *
-     * @example
-     * ```typescript
-     * // Listen for score updates
-     * runtime.onBridge('score', (data) => {
-     *   updateScoreboard(data.value, data.combo);
-     * });
-     *
-     * // Listen for notifications
-     * runtime.onBridge('notification', (data) => {
-     *   showToast(data.title, data.message);
-     * });
-     *
-     * // Wildcard handler for all channels
-     * runtime.onBridge('*', (channel, data) => {
-     *   console.log(`Received ${channel}:`, data);
-     * });
-     * ```
+     * Get mobile vibration processor
      */
-    onBridge<T = unknown>(channel: string, handler: (data: T) => void): void;
+    getMobileVibration(): MobileVibration;
     /**
-     * Remove a specific bridge handler
-     *
-     * @param channel - Channel name
-     * @param handler - The exact handler function to remove
-     *
-     * @example
-     * ```typescript
-     * const handler = (data) => console.log(data);
-     * runtime.onBridge('score', handler);
-     *
-     * // Later, remove the handler
-     * runtime.offBridge('score', handler);
-     * ```
+     * Collect and apply input to user
      */
-    offBridge<T = unknown>(channel: string, handler: (data: T) => void): void;
+    collectAndApply(user: User, canvas: HTMLCanvasElement | null, displayWidth: number, displayHeight: number, rendererOffsets: {
+        offsetX: number;
+        offsetY: number;
+    }): void;
     /**
-     * Remove all bridge handlers for a channel (or all channels if not specified)
-     *
-     * Useful for cleanup in React useEffect or component unmount.
-     *
-     * @param channel - Optional channel name. If omitted, removes all handlers.
-     *
-     * @example
-     * ```typescript
-     * // Remove all handlers for 'score' channel
-     * runtime.removeAllBridgeHandlers('score');
-     *
-     * // Remove ALL bridge handlers
-     * runtime.removeAllBridgeHandlers();
-     * ```
+     * Process vibration commands from user
      */
-    removeAllBridgeHandlers(channel?: string): void;
+    processVibrationCommands(user: User): void;
+}
+
+/**
+ * Audio Feature
+ *
+ * Handles sound playback and spatial audio.
+ * Can be omitted for silent clients (spectators, embeds without sound).
+ */
+
+interface AudioFeatureOptions {
+    debug?: boolean;
+}
+declare class AudioFeature {
+    private audioManager;
+    private debug;
+    constructor(options?: AudioFeatureOptions);
+    /**
+     * Initialize audio context (should be called after user interaction)
+     */
+    initialize(): void;
+    /**
+     * Play the start sound (used with autoplay overlay)
+     */
+    playStartSound(): void;
+    /**
+     * Stop all sounds
+     */
+    stopAll(): void;
+    /**
+     * Destroy and cleanup
+     */
+    destroy(): void;
+    /**
+     * Get the AudioManager instance
+     */
+    getManager(): AudioManager;
+    /**
+     * Get the AudioContext
+     */
+    getContext(): AudioContext | null;
+    /**
+     * Inject audio processor into user
+     */
+    injectIntoUser(user: User): void;
+    /**
+     * Process audio commands from user
+     */
+    processAudioCommands(user: User): void;
+    /**
+     * Load sounds from Core's SoundRegistry into AudioManager's SoundBank
+     */
+    loadSoundsFromRegistry(core: Core): Promise<void>;
+    private log;
+}
+
+/**
+ * PostProcess Feature
+ *
+ * Handles scanlines, ambient effects, grid overlay, and scaling modes.
+ * Can be omitted for minimal clients without visual effects.
+ */
+
+interface PostProcessFeatureOptions {
+    debug?: boolean;
+}
+declare class PostProcessFeature {
+    private overlay;
+    private orderCollector;
+    private debug;
+    constructor(container: HTMLElement, options?: PostProcessFeatureOptions);
+    /**
+     * Destroy and cleanup
+     */
+    destroy(): void;
+    /**
+     * Get the PostProcessOverlay instance
+     */
+    getOverlay(): PostProcessOverlay;
+    /**
+     * Sync overlay with renderer dimensions after font change
+     */
+    syncWithRenderer(renderer: {
+        getCellWidth(): number;
+        getCellHeight(): number;
+        getCurrentScale(): number;
+        getGridSize(): {
+            cols: number;
+            rows: number;
+        };
+    }): void;
+    /**
+     * Process post-process commands from user (converts to orders and applies)
+     */
+    processCommands(user: User, renderer: any): void;
+    /**
+     * Apply post-process orders (used by both local and network modes)
+     */
+    applyOrders(orders: AnyPostProcessOrder[], renderer: any): void;
+    private applyAmbientEffect;
+    private applyScalingMode;
+    private applyGridConfig;
+    private patternFromType;
     private log;
 }
 
-export { ClientRuntime, RendererType };
-export type { BaseClientRuntimeOptions, ClientRuntimeMode, ClientRuntimeOptions, ClientRuntimeStats, ConnectedModeOptions, FrameTiming, LocalModeOptions, RenderMode };
+export { AudioFeature, BaseClientRuntime, ClientRuntime, InputFeature, PostProcessFeature, RendererType };
+export type { AudioFeatureOptions, BaseClientRuntimeOptions, BaseRuntimeOptions, BaseRuntimeStats, ClientRuntimeMode, ClientRuntimeOptions, ClientRuntimeStats, ConnectedModeOptions, FrameTiming$1 as FrameTiming, InputFeatureOptions, LocalModeOptions, PostProcessFeatureOptions, RenderMode };