stelo 1.0.1

package/dist/stream.js

@@ -0,0 +1,298 @@
+"use strict";
+// ============================================================================
+// Stelo — Real-Time Screen Streaming API
+// ============================================================================
+// Ultra-low-latency continuous screen capture at up to 4K resolution.
+//
+// Designed for automation workloads, background tasks, and real-time vision pipelines
+// that need a non-stop live feed of the screen while the user works.
+//
+// Features:
+//   - Continuous real-time capture at configurable FPS (up to 120fps)
+//   - 4K native resolution support
+//   - Background capture thread (never blocks Node.js event loop)
+//   - Double-buffered frames with zero-copy handoff
+//   - Per-frame metadata: cursor position, timestamp, sequence, FPS
+//   - Event-driven: onFrame callback, polling, or async iteration
+//   - Region capture & downscaling for bandwidth-constrained scenarios
+//
+// @example
+// ```typescript
+// import { stream } from 'stelo';
+//
+// // Start a 4K 60fps live stream
+// stream.start({ fps: 60 });
+//
+// // Grab frames in a loop
+// setInterval(() => {
+//   const frame = stream.latestFrame();
+//   if (frame) {
+//     model.processFrame(frame.data, frame.width, frame.height);
+//   }
+// }, 16);
+//
+// // Or use the event-driven API
+// stream.onFrame((frame) => {
+//   console.log(`Frame #${frame.sequence} ${frame.width}x${frame.height} @ ${frame.measuredFps}fps`);
+// });
+//
+// // Or async iteration
+// for await (const frame of stream) {
+//   await processFrame(frame);
+// }
+//
+// stream.stop();
+// ```
+// ============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.stream = void 0;
+const native = require('../index.js');
+// ── Stream API ──────────────────────────────────────────────────────────────
+/**
+ * Real-time screen streaming engine.
+ *
+ * Provides continuous, non-blocking screen capture at up to 4K resolution
+ * and 120fps. The capture runs on a dedicated native thread, so it never
+ * blocks the Node.js event loop.
+ *
+ * @example
+ * ```typescript
+ * import { stream } from 'stelo';
+ *
+ * // Start 4K stream at 60fps
+ * stream.start({ fps: 60 });
+ *
+ * // Get latest frame for processing
+ * const frame = stream.latestFrame();
+ *
+ * // Get stream performance info
+ * const stats = stream.stats();
+ * console.log(`Running at ${stats.currentFps} fps`);
+ *
+ * // Subscribe to frames
+ * const unsub = stream.onFrame(frame => {
+ *   // Process every frame
+ * });
+ *
+ * // Async iteration
+ * for await (const frame of stream) {
+ *   await analyzeFrame(frame);
+ * }
+ *
+ * stream.stop();
+ * ```
+ */
+exports.stream = {
+    // Internal state for frame polling
+    _frameHandlers: [],
+    _pollTimer: null,
+    _lastSequence: 0,
+    /**
+     * Start a continuous real-time screen stream.
+     *
+     * The stream runs on a dedicated native thread and captures frames
+     * continuously at the configured FPS. Frames are double-buffered,
+     * so reading never blocks capture.
+     *
+     * @param config - Stream configuration (fps, region, scale, buffer)
+     */
+    start(config) {
+        const nativeConfig = {};
+        if (config?.fps !== undefined)
+            nativeConfig.fps = config.fps;
+        if (config?.scale !== undefined)
+            nativeConfig.scale = config.scale;
+        if (config?.bufferSize !== undefined)
+            nativeConfig.bufferSize = config.bufferSize;
+        if (config?.region) {
+            nativeConfig.regionX = config.region.x;
+            nativeConfig.regionY = config.region.y;
+            nativeConfig.regionWidth = config.region.width;
+            nativeConfig.regionHeight = config.region.height;
+        }
+        native.streamStart(nativeConfig);
+        // Prime: wait briefly for the native capture thread to produce the first
+        // frame so `latestFrame()` calls immediately after `start()` are more
+        // likely to return a valid frame in tests and short-lived usage.
+        try {
+            // native.streamWaitForFrame blocks until a frame or timeout (ms)
+            native.streamWaitForFrame && native.streamWaitForFrame(500);
+        }
+        catch {
+            // Ignore any errors — stream will continue running and subsequent
+            // calls to latestFrame()/waitForFrame() will succeed.
+        }
+        // Start polling for frame handlers if any are registered
+        this._startPollingIfNeeded();
+    },
+    /**
+     * Stop the screen stream and release all resources.
+     */
+    stop() {
+        this._stopPolling();
+        this._lastSequence = 0;
+        native.streamStop();
+    },
+    /**
+     * Check if a stream is currently running.
+     */
+    isRunning() {
+        return native.streamIsRunning();
+    },
+    /**
+     * Get the latest captured frame.
+     * Returns null if no frames have been captured yet.
+     *
+    * This is the primary method for real-time automation — call it whenever
+     * you need the current screen state.
+     */
+    latestFrame() {
+        const frame = native.streamGetLatestFrame();
+        return frame ? toStreamFrame(frame) : null;
+    },
+    /**
+     * Get the most recent N frames from the ring buffer.
+     * Useful for temporal analysis (motion detection, change tracking).
+     *
+     * @param count - Number of recent frames to retrieve (default: 3)
+     */
+    recentFrames(count) {
+        const frames = native.streamGetRecentFrames(count ?? 3);
+        return frames.map(toStreamFrame);
+    },
+    /**
+     * Wait for the next new frame (blocks until available or timeout).
+     * Returns null if timeout is reached before a new frame arrives.
+     *
+     * @param timeoutMs - Maximum time to wait in ms (default: 1000)
+     */
+    waitForFrame(timeoutMs) {
+        const frame = native.streamWaitForFrame(timeoutMs ?? 1000);
+        return frame ? toStreamFrame(frame) : null;
+    },
+    /**
+     * Get stream performance statistics.
+     */
+    stats() {
+        const s = native.streamGetStats();
+        return {
+            isRunning: s.isRunning,
+            totalFrames: s.totalFrames,
+            droppedFrames: s.droppedFrames,
+            currentFps: s.currentFps,
+            targetFps: s.targetFps,
+            uptimeMs: s.uptimeMs,
+        };
+    },
+    /**
+     * Register a callback that fires for every new frame.
+     * Returns an unsubscribe function.
+     *
+     * @param handler - Function called with each new frame
+     * @returns Unsubscribe function
+     *
+     * @example
+     * ```typescript
+     * const unsub = stream.onFrame(frame => {
+     *   console.log(`Frame ${frame.sequence}: ${frame.width}x${frame.height}`);
+     * });
+     *
+     * // Later: stop receiving frames
+     * unsub();
+     * ```
+     */
+    onFrame(handler) {
+        this._frameHandlers.push(handler);
+        this._startPollingIfNeeded();
+        return () => {
+            const idx = this._frameHandlers.indexOf(handler);
+            if (idx !== -1) {
+                this._frameHandlers.splice(idx, 1);
+            }
+            if (this._frameHandlers.length === 0) {
+                this._stopPolling();
+            }
+        };
+    },
+    /**
+     * Async iterator for frames. Yields new frames as they arrive.
+     *
+     * @example
+     * ```typescript
+     * stream.start({ fps: 30 });
+     * for await (const frame of stream) {
+     *   const result = await model.analyze(frame.data);
+     *   if (result.found) break;
+     * }
+     * stream.stop();
+     * ```
+     */
+    [Symbol.asyncIterator]() {
+        const self = this;
+        return {
+            async next() {
+                if (!self.isRunning()) {
+                    return { done: true, value: undefined };
+                }
+                const frame = self.waitForFrame(5000);
+                if (!frame) {
+                    return { done: true, value: undefined };
+                }
+                return { done: false, value: frame };
+            },
+            [Symbol.asyncIterator]() {
+                return this;
+            },
+        };
+    },
+    // ── Internal Polling ────────────────────────────────────────────────────
+    /** @internal */
+    _startPollingIfNeeded() {
+        if (this._pollTimer !== null)
+            return;
+        if (this._frameHandlers.length === 0)
+            return;
+        if (!this.isRunning())
+            return;
+        // Poll at 1ms intervals (native code handles actual FPS)
+        this._pollTimer = setInterval(() => {
+            if (!this.isRunning() || this._frameHandlers.length === 0) {
+                this._stopPolling();
+                return;
+            }
+            const frame = this.latestFrame();
+            if (frame && frame.sequence > this._lastSequence) {
+                this._lastSequence = frame.sequence;
+                for (const handler of this._frameHandlers) {
+                    try {
+                        handler(frame);
+                    }
+                    catch {
+                        // Don't let handler errors kill the poll loop
+                    }
+                }
+            }
+        }, 1);
+    },
+    /** @internal */
+    _stopPolling() {
+        if (this._pollTimer !== null) {
+            clearInterval(this._pollTimer);
+            this._pollTimer = null;
+        }
+    },
+};
+// ── Helpers ─────────────────────────────────────────────────────────────────
+function toStreamFrame(raw) {
+    return {
+        data: raw.data,
+        width: raw.width,
+        height: raw.height,
+        sequence: raw.sequence,
+        timestampMs: raw.timestampMs,
+        measuredFps: raw.measuredFps,
+        cursorX: raw.cursorX,
+        cursorY: raw.cursorY,
+    };
+}
+//# sourceMappingURL=stream.js.map

package/dist/stream.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream.js","sourceRoot":"","sources":["../ts/stream.ts"],"names":[],"mappings":"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"}

package/dist/telemetry.d.ts

@@ -0,0 +1,223 @@
+/**
+ * Event severity levels for telemetry
+ */
+export type TelemetrySeverity = 'debug' | 'info' | 'warn' | 'error' | 'critical';
+/**
+ * Operation categories for structured logging
+ */
+export type OperationCategory = 'mouse' | 'keyboard' | 'screen' | 'window' | 'safety' | 'stream' | 'system';
+/**
+ * Telemetry event payload
+ */
+export interface TelemetryEvent {
+    /** Unique event ID */
+    id: string;
+    /** ISO timestamp */
+    timestamp: string;
+    /** Event severity */
+    severity: TelemetrySeverity;
+    /** Operation category */
+    category: OperationCategory;
+    /** Operation name (e.g., 'mouse.click', 'keyboard.type') */
+    operation: string;
+    /** Duration in milliseconds (if applicable) */
+    durationMs?: number;
+    /** Success or failure */
+    success: boolean;
+    /** Error details (if failed) */
+    error?: {
+        code: string;
+        message: string;
+        recoverable: boolean;
+    };
+    /** Additional context */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Performance metrics snapshot
+ */
+export interface PerformanceMetrics {
+    /** Total operations executed */
+    totalOperations: number;
+    /** Successful operations */
+    successCount: number;
+    /** Failed operations */
+    failureCount: number;
+    /** Average operation duration (ms) */
+    avgDurationMs: number;
+    /** P95 operation duration (ms) */
+    p95DurationMs: number;
+    /** P99 operation duration (ms) */
+    p99DurationMs: number;
+    /** Operations per second (last minute) */
+    opsPerSecond: number;
+    /** Active circuit breakers */
+    activeCircuitBreakers: string[];
+    /** Uptime in milliseconds */
+    uptimeMs: number;
+}
+/**
+ * Health check result
+ */
+export interface HealthCheckResult {
+    /** Overall health status */
+    status: 'healthy' | 'degraded' | 'unhealthy';
+    /** Individual check results */
+    checks: {
+        name: string;
+        status: 'pass' | 'fail' | 'warn';
+        message?: string;
+        durationMs: number;
+    }[];
+    /** Timestamp of check */
+    timestamp: string;
+}
+type TelemetryHandler = (event: TelemetryEvent) => void;
+type MetricsHandler = (metrics: PerformanceMetrics) => void;
+/**
+ * Telemetry system for enterprise observability
+ *
+ * @example
+ * ```typescript
+ * import { telemetry } from 'stelo';
+ *
+ * // Enable telemetry
+ * telemetry.enable();
+ *
+ * // Subscribe to events
+ * telemetry.onEvent((event) => {
+ *   console.log(`[${event.severity}] ${event.operation}: ${event.success}`);
+ * });
+ *
+ * // Get performance metrics
+ * const metrics = telemetry.getMetrics();
+ * console.log(`Ops/sec: ${metrics.opsPerSecond}`);
+ *
+ * // Run health checks
+ * const health = await telemetry.healthCheck();
+ * console.log(`System status: ${health.status}`);
+ * ```
+ */
+export declare const telemetry: {
+    /**
+     * Enable telemetry collection
+     */
+    enable(): void;
+    /**
+     * Disable telemetry collection
+     */
+    disable(): void;
+    /**
+     * Check if telemetry is enabled
+     */
+    isEnabled(): boolean;
+    /**
+     * Enable metrics collection
+     */
+    enableMetrics(): void;
+    /**
+     * Disable metrics collection
+     */
+    disableMetrics(): void;
+    /**
+     * Subscribe to telemetry events
+     */
+    onEvent(handler: TelemetryHandler): () => void;
+    /**
+     * Subscribe to periodic metrics updates
+     */
+    onMetrics(handler: MetricsHandler): () => void;
+    /**
+     * Emit a telemetry event
+     * @internal Used by Stelo internals
+     */
+    emit(category: OperationCategory, operation: string, success: boolean, options?: {
+        severity?: TelemetrySeverity;
+        durationMs?: number;
+        error?: {
+            code: string;
+            message: string;
+            recoverable: boolean;
+        };
+        metadata?: Record<string, unknown>;
+    }): void;
+    /**
+     * Get current performance metrics
+     */
+    getMetrics(): PerformanceMetrics;
+    /**
+     * Run system health checks
+     */
+    healthCheck(): Promise<HealthCheckResult>;
+    /**
+     * Reset all metrics
+     */
+    resetMetrics(): void;
+    /**
+     * Wrap an operation with telemetry tracking
+     */
+    track<T>(category: OperationCategory, operation: string, fn: () => T, metadata?: Record<string, unknown>): T;
+    /**
+     * Wrap an async operation with telemetry tracking
+     */
+    trackAsync<T>(category: OperationCategory, operation: string, fn: () => Promise<T>, metadata?: Record<string, unknown>): Promise<T>;
+};
+/**
+ * Circuit breaker state
+ */
+export type CircuitState = 'closed' | 'open' | 'half-open';
+/**
+ * Circuit breaker configuration
+ */
+export interface CircuitBreakerOptions {
+    /** Failure threshold before opening (default: 5) */
+    failureThreshold?: number;
+    /** Time to wait before half-open state (ms, default: 30000) */
+    resetTimeoutMs?: number;
+    /** Successes needed to close from half-open (default: 2) */
+    successThreshold?: number;
+}
+/**
+ * Circuit breaker for fault tolerance
+ */
+export declare class CircuitBreaker {
+    readonly name: string;
+    private state;
+    private failureCount;
+    private successCount;
+    private lastFailureTime;
+    private readonly failureThreshold;
+    private readonly resetTimeoutMs;
+    private readonly successThreshold;
+    constructor(name: string, options?: CircuitBreakerOptions);
+    /**
+     * Get current circuit state
+     */
+    getState(): CircuitState;
+    /**
+     * Check if circuit is open (blocking)
+     */
+    isOpen(): boolean;
+    /**
+     * Record a successful operation
+     */
+    recordSuccess(): void;
+    /**
+     * Record a failed operation
+     */
+    recordFailure(): void;
+    /**
+     * Execute an operation with circuit breaker protection
+     */
+    execute<T>(fn: () => Promise<T>): Promise<T>;
+    /**
+     * Force reset the circuit breaker
+     */
+    reset(): void;
+}
+/**
+ * Get all registered circuit breakers
+ */
+export declare function getCircuitBreakers(): CircuitBreaker[];
+export {};
+//# sourceMappingURL=telemetry.d.ts.map

package/dist/telemetry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry.d.ts","sourceRoot":"","sources":["../ts/telemetry.ts"],"names":[],"mappings":"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"}