@hexaversia/fovea-sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Fovea Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,83 @@
+# Fovea SDK
+
+**Foveated Streaming Engine** for High-Performance Screen Sharing.
+
+![Fovea Banner](https://via.placeholder.com/800x200?text=Fovea+SDK)
+
+## Overview
+Fovea uses **WebAssembly (Rust)** to perform "Foveated Rendering" on video streams entirely on the client side. It detects changes in the screen and only sends high-resolution updates for the active region (ROI), while blurring the static background. This results in **massive bandwidth savings (up to 90%)** for screen sharing applications.
+
+## Installation
+
+```bash
+npm install fovea-sdk
+```
+
+(Note: During private beta, install from local path or private registry)
+
+## Usage
+
+### 1. Electron (Node.js)
+
+```javascript
+const FoveaEngine = require('fovea-sdk');
+const path = require('path');
+
+async function start() {
+    const engine = new FoveaEngine({ blurAmount: '12px' });
+    
+    // Initialize with local WASM file
+    await engine.initialize({ 
+        wasmPath: path.join(__dirname, 'node_modules/fovea-sdk/fovea_rs/pkg/fovea_wasm_bg.wasm') 
+    });
+
+    function loop() {
+        // Process video frame -> canvas
+        const result = engine.process(videoElement, outputCanvas);
+        
+        if (result && result.type === 'foveated') {
+             console.log(`ROI: ${JSON.stringify(result.bbox)}`);
+        }
+        requestAnimationFrame(loop);
+    }
+}
+```
+
+### 2. Browser (React/Vue/Vanilla)
+
+Copy the `.wasm` file to your public assets folder first.
+
+```javascript
+import FoveaEngine from 'fovea-sdk';
+
+const engine = new FoveaEngine();
+
+// Initialize by fetching WASM from public URL
+await engine.initialize({ 
+    wasmPath: '/assets/fovea_wasm_bg.wasm' 
+});
+
+// ... use engine.process() in your render loop
+```
+
+## API
+
+### `new FoveaEngine(config)`
+- `config.blurAmount`: CSS blur string (default `'8px'`)
+- `config.diffThreshold`: Sensitivity (0-255) for change detection (default `30`)
+
+### `async initialize(options)`
+- `options.wasmPath`: Path (Node) or URL (Browser) to the `.wasm` binary.
+- `options.wasmBuffer`: ArrayBuffer of the WASM binary (optional alternative).
+
+### `process(video, canvas)`
+- `video`: Source HTMLVideoElement
+- `canvas`: Target HTMLCanvasElement (where the foveated effect is drawn)
+- Returns: `{ type, bbox, isKeyframe }`
+
+## 🤝 Contributing
+Want to improve the engine? We welcome optimizations!
+Since the core is written in Rust, please see our [Contribution Guide](CONTRIBUTING.md) for build instructions.
+
+## License
+MIT

package/index.js

@@ -0,0 +1,220 @@
+// Universal Import Strategy
+let fs = null;
+let path = null;
+
+// Try to load Node modules if 'require' is available (Node.js or Electron)
+if (typeof require !== 'undefined') {
+    try {
+        fs = require('fs');
+        path = require('path');
+    } catch (e) {
+        // Bundlers might define 'require' but fail to resolve 'fs'
+        console.warn("[Fovea SDK] 'require' present but failed to load fs/path:", e);
+    }
+}
+
+// Determine environment
+const isNode = typeof process !== 'undefined' && process.versions && process.versions.node;
+
+
+/**
+ * Fovea Engine SDK
+ * 
+ * Usage:
+ * const engine = new FoveaEngine();
+ * await engine.initialize({ wasmPath: '/path/to/fovea.wasm' }); // Browser
+ * await engine.initialize({ wasmPath: __dirname + '/fovea.wasm' }); // Node
+ * 
+ * const result = engine.process(videoElement, canvasElement);
+ */
+class FoveaEngine {
+    constructor(config = {}) {
+        this.wasmInstance = null;
+        this.calculate_diff = null;
+        this.config = {
+            blurAmount: config.blurAmount || '8px',
+            diffThreshold: config.diffThreshold || 30,
+            debug: config.debug || false
+        };
+
+        // State
+        this.prevFrameData = null;
+        this.frameCount = 0;
+        this.keyframeInterval = 300;
+
+        // Internal scratch canvas
+        this.diffCanvas = null;
+        this.diffCtx = null;
+    }
+
+    async initialize(options = {}) {
+        if (this.wasmInstance) return;
+
+        console.log("[Fovea SDK] Initializing...");
+
+        let wasmBytes;
+
+        // 1. Try to load WASM based on Environment
+        if (isNode && options.wasmPath) {
+            // Node.js: Read from FS
+            try {
+                wasmBytes = fs.readFileSync(options.wasmPath);
+            } catch (e) {
+                throw new Error(`[Fovea SDK] Failed to read WASM file at ${options.wasmPath}: ${e.message}`);
+            }
+        } else if (!isNode && options.wasmPath) {
+            // Browser: Fetch URL
+            // Users should pass the URL where they host the .wasm file
+            // OR pass a pre-loaded ArrayBuffer/Response
+            if (typeof options.wasmPath === 'string') {
+                // It's a URL
+                const response = await fetch(options.wasmPath);
+                wasmBytes = await response.arrayBuffer();
+            } else {
+                // Assume it's already bytes/response
+                wasmBytes = options.wasmPath;
+            }
+        } else if (options.wasmBuffer) {
+            // Direct Buffer passed
+            wasmBytes = options.wasmBuffer;
+        } else {
+            throw new Error("[Fovea SDK] You must provide 'wasmPath' or 'wasmBuffer' to initialize.");
+        }
+
+        // 2. Instantiate WebAssembly
+        // We need the 'init' function from the pkg.
+        // Since we can't easily 'require' an ESM-only pkg in a generic CJS/UMD without a build step,
+        // We will assume the user environment supports dynamic import() OR 
+        // strictly speaking, for this "raw" SDK, we might need to inline a lightweight loader.
+
+        // APPROACH: We will use the 'fovea_wasm.js' generated by wasm-pack 
+        // but we need to locate it.
+        // For simplicity in this raw version, we'll try to dynamically import the relative file if possible,
+        // otherwise we expect the USER to pass the module exports?
+        // Let's try importing the local pkg file.
+
+        try {
+            // NOTE: This path depends on where this file is located relative to pkg
+            // If running in node, require works.
+            // If running in browser (via bundler), import works.
+            // This is the hardest part of "Universal" without a build step.
+
+            // Allow user to pass the init function if they imported it themselves
+            const initFunc = options.initFunction || (await import('./fovea_rs/pkg/fovea_wasm.js')).default;
+            const diffFunc = options.diffFunction || (await import('./fovea_rs/pkg/fovea_wasm.js')).calculate_diff;
+
+            await initFunc(wasmBytes);
+            this.calculate_diff = diffFunc;
+
+            console.log("[Fovea SDK] WASM Ready.");
+            this.wasmInstance = true;
+
+        } catch (e) {
+            console.error(e);
+            throw new Error("[Fovea SDK] Failed to instantiate WASM module. Ensure generated pkg is available.");
+        }
+    }
+
+    /**
+     * Main Processing Loop Step
+     * Call this on every animation frame.
+     * @param {HTMLVideoElement} video Source video
+     * @param {HTMLCanvasElement} outputCanvas Output canvas (visible)
+     * @returns {Object} { type: 'keyframe'|'foveated', dataUrl: string, stats: object }
+     */
+    process(video, outputCanvas) {
+        if (!this.wasmInstance) {
+            console.warn("[Fovea SDK] Not initialized.");
+            return null;
+        }
+        if (video.paused || video.ended) return null;
+
+        const w = outputCanvas.width;
+        const h = outputCanvas.height;
+        const ctx = outputCanvas.getContext('2d', { willReadFrequently: true });
+
+        this.frameCount++;
+        let isKeyframe = (this.frameCount === 1 || this.frameCount % this.keyframeInterval === 0);
+
+        // --- 1. Downscale for diffing ---
+        const diffScale = 0.1;
+        const dw = Math.floor(w * diffScale);
+        const dh = Math.floor(h * diffScale);
+
+        if (!this.diffCanvas) {
+            // Try OffscreenCanvas (Worker/Modern) or document (Browser)
+            if (typeof OffscreenCanvas !== 'undefined') {
+                this.diffCanvas = new OffscreenCanvas(dw, dh);
+            } else {
+                this.diffCanvas = document.createElement('canvas');
+                this.diffCanvas.width = dw;
+                this.diffCanvas.height = dh;
+            }
+            this.diffCtx = this.diffCanvas.getContext('2d', { willReadFrequently: true });
+        }
+
+        // Resize if needed
+        if (this.diffCanvas.width !== dw) this.diffCanvas.width = dw;
+        if (this.diffCanvas.height !== dh) this.diffCanvas.height = dh;
+
+        this.diffCtx.drawImage(video, 0, 0, dw, dh);
+
+        const currentFrameData = this.diffCtx.getImageData(0, 0, dw, dh);
+        const currentPixels = new Uint8Array(currentFrameData.data.buffer);
+
+        // --- 2. Calculate Diff (WASM) ---
+        let bbox = { min_x: 0, max_x: 0, min_y: 0, max_y: 0, changed: false };
+
+        if (this.prevFrameData && this.prevFrameData.length === currentPixels.length && !isKeyframe) {
+            try {
+                bbox = this.calculate_diff(currentPixels, this.prevFrameData, dw, dh, this.config.diffThreshold);
+            } catch (e) {
+                console.warn("[Fovea SDK] WASM Diff Error, forcing keyframe", e);
+                isKeyframe = true;
+            }
+        } else {
+            isKeyframe = true;
+        }
+
+        this.prevFrameData = new Uint8Array(currentPixels); // Cache
+
+        // --- 3. Render Output ---
+        if (isKeyframe) {
+            ctx.filter = 'none';
+            ctx.drawImage(video, 0, 0, w, h);
+        } else {
+            ctx.filter = `blur(${this.config.blurAmount})`;
+            ctx.drawImage(video, 0, 0, w, h); // Blurred Background
+
+            if (bbox.changed) {
+                ctx.filter = 'none';
+                const scale = 1 / diffScale;
+                const roiX = Math.max(0, (bbox.min_x * scale) - 20);
+                const roiY = Math.max(0, (bbox.min_y * scale) - 20);
+                const roiW = Math.min(w - roiX, (bbox.max_x - bbox.min_x) * scale + 40);
+                const roiH = Math.min(h - roiY, (bbox.max_y - bbox.min_y) * scale + 40);
+
+                ctx.save();
+                ctx.beginPath();
+                ctx.rect(roiX, roiY, roiW, roiH);
+                ctx.clip();
+                ctx.drawImage(video, 0, 0, w, h); // Sharp ROI
+                ctx.restore();
+            }
+        }
+
+        return {
+            type: isKeyframe ? 'keyframe' : 'foveated',
+            bbox: bbox,
+            isKeyframe: isKeyframe
+        };
+    }
+}
+
+// Export for CommonJS and ESM
+if (typeof module !== 'undefined' && module.exports) {
+    module.exports = FoveaEngine;
+} else {
+    // Browser Global
+    window.FoveaEngine = FoveaEngine;
+}

package/package.json

@@ -0,0 +1,37 @@
+{
+    "name": "@hexaversia/fovea-sdk",
+    "version": "0.1.0",
+    "description": "Foveated Streaming Engine: High-performance, bandwidth-efficient screen sharing using WASM and Dynamic ROI.",
+    "main": "index.js",
+    "types": "index.d.ts",
+    "files": [
+        "index.js",
+        "fovea_rs/pkg"
+    ],
+    "scripts": {
+        "test": "echo \"Error: no test specified\" && exit 1"
+    },
+    "keywords": [
+        "foveated",
+        "streaming",
+        "wasm",
+        "screen-sharing",
+        "bandwidth-optimization",
+        "real-time",
+        "video-analysis",
+        "ai",
+        "computer-vision"
+    ],
+    "author": "Hexaversia Team",
+    "license": "MIT",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/agentifyanchor/fovea-sdk.git"
+    },
+    "bugs": {
+        "url": "https://github.com/agentifyanchor/fovea-sdk/issues"
+    },
+    "homepage": "https://agentifyanchor.github.io/fovea-sdk",
+    "dependencies": {},
+    "devDependencies": {}
+}