@runanywhere/web 0.1.0-beta.6 → 0.1.0-beta.7

package/dist/Infrastructure/ExtensionPoint.js

@@ -0,0 +1,178 @@
+/**
+ * ExtensionPoint - Backend registration API
+ *
+ * Follows the React Native SDK's Provider pattern. Backend packages
+ * (e.g. @runanywhere/web-llamacpp, @runanywhere/web-onnx) register
+ * themselves with the core SDK via this API, declaring what capabilities
+ * they provide.
+ *
+ * Usage:
+ *   // In @runanywhere/web-llamacpp:
+ *   import { ExtensionPoint, BackendCapability } from '@runanywhere/web';
+ *
+ *   ExtensionPoint.registerBackend({
+ *     id: 'llamacpp',
+ *     capabilities: [BackendCapability.LLM, BackendCapability.VLM, ...],
+ *     cleanup() { ... },
+ *   });
+ *
+ *   // In core (VoicePipeline, etc.) — runtime lookup:
+ *   const stt = ExtensionPoint.getExtensionForCapability(BackendCapability.STT);
+ */
+import { SDKLogger } from '../Foundation/SDKLogger';
+const logger = new SDKLogger('ExtensionPoint');
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+/** Capabilities that a backend can provide. */
+export var BackendCapability;
+(function (BackendCapability) {
+    BackendCapability["LLM"] = "llm";
+    BackendCapability["VLM"] = "vlm";
+    BackendCapability["STT"] = "stt";
+    BackendCapability["TTS"] = "tts";
+    BackendCapability["VAD"] = "vad";
+    BackendCapability["Embeddings"] = "embeddings";
+    BackendCapability["Diffusion"] = "diffusion";
+    BackendCapability["ToolCalling"] = "toolCalling";
+    BackendCapability["StructuredOutput"] = "structuredOutput";
+})(BackendCapability || (BackendCapability = {}));
+/**
+ * Typed service keys for cross-package singleton access.
+ *
+ * Backend packages register service instances (e.g. TextGeneration, STT, TTS)
+ * under these keys during their registration phase. Core code (e.g. VoicePipeline)
+ * retrieves them at runtime via `ExtensionPoint.getService(ServiceKey.XXX)` instead
+ * of relying on untyped globalThis keys.
+ */
+export var ServiceKey;
+(function (ServiceKey) {
+    ServiceKey["TextGeneration"] = "textGeneration";
+    ServiceKey["STT"] = "stt";
+    ServiceKey["TTS"] = "tts";
+    ServiceKey["VLM"] = "vlm";
+    ServiceKey["Embeddings"] = "embeddings";
+    ServiceKey["Diffusion"] = "diffusion";
+    ServiceKey["ToolCalling"] = "toolCalling";
+    ServiceKey["VAD"] = "vad";
+})(ServiceKey || (ServiceKey = {}));
+// ---------------------------------------------------------------------------
+// ExtensionPoint Singleton
+// ---------------------------------------------------------------------------
+class ExtensionPointImpl {
+    backends = new Map();
+    capabilityMap = new Map();
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    services = new Map();
+    /**
+     * Register a backend extension.
+     * Idempotent — re-registering the same id is a no-op.
+     */
+    registerBackend(extension) {
+        if (this.backends.has(extension.id)) {
+            logger.debug(`Backend '${extension.id}' already registered, skipping`);
+            return;
+        }
+        this.backends.set(extension.id, extension);
+        for (const cap of extension.capabilities) {
+            if (this.capabilityMap.has(cap)) {
+                logger.warning(`Capability '${cap}' already provided by '${this.capabilityMap.get(cap).id}', ` +
+                    `overriding with '${extension.id}'`);
+            }
+            this.capabilityMap.set(cap, extension);
+        }
+        logger.info(`Backend '${extension.id}' registered — capabilities: [${extension.capabilities.join(', ')}]`);
+    }
+    /** Get a backend by its id. */
+    getBackend(id) {
+        return this.backends.get(id);
+    }
+    /** Check if a capability is available (i.e. a backend providing it is registered). */
+    hasCapability(capability) {
+        return this.capabilityMap.has(capability);
+    }
+    /** Get the backend extension providing a given capability. */
+    getExtensionForCapability(capability) {
+        return this.capabilityMap.get(capability);
+    }
+    /**
+     * Require that a capability is available. Throws a clear error if not.
+     * Use in extension methods that depend on a backend being registered.
+     */
+    requireCapability(capability) {
+        if (!this.capabilityMap.has(capability)) {
+            const packageHint = capability === BackendCapability.LLM ||
+                capability === BackendCapability.VLM ||
+                capability === BackendCapability.Embeddings ||
+                capability === BackendCapability.Diffusion ||
+                capability === BackendCapability.ToolCalling ||
+                capability === BackendCapability.StructuredOutput
+                ? '@runanywhere/web-llamacpp'
+                : '@runanywhere/web-onnx';
+            throw new Error(`Capability '${capability}' not available. ` +
+                `Install and register the ${packageHint} package.`);
+        }
+    }
+    // -------------------------------------------------------------------------
+    // Service Registry — typed singleton access for cross-package communication
+    // -------------------------------------------------------------------------
+    /**
+     * Register a service singleton under a typed key.
+     * Backend packages call this during their registration phase.
+     */
+    registerService(key, service) {
+        if (this.services.has(key)) {
+            logger.debug(`Service '${key}' already registered, overwriting`);
+        }
+        this.services.set(key, service);
+    }
+    /**
+     * Retrieve a registered service singleton.
+     * Returns undefined if the service is not registered yet.
+     */
+    getService(key) {
+        return this.services.get(key);
+    }
+    /**
+     * Retrieve a registered service or throw a descriptive error.
+     * Use in code that requires a specific backend to be registered.
+     */
+    requireService(key, packageHint) {
+        const service = this.services.get(key);
+        if (!service) {
+            const hint = packageHint ?? (key === ServiceKey.STT || key === ServiceKey.TTS || key === ServiceKey.VAD
+                ? '@runanywhere/web-onnx'
+                : '@runanywhere/web-llamacpp');
+            throw new Error(`Service '${key}' not available. Install and register the ${hint} package.`);
+        }
+        return service;
+    }
+    /** Remove a registered service. */
+    removeService(key) {
+        this.services.delete(key);
+    }
+    /**
+     * Cleanup all registered backends in reverse registration order.
+     * Called during SDK shutdown.
+     */
+    cleanupAll() {
+        const entries = [...this.backends.entries()].reverse();
+        for (const [id, backend] of entries) {
+            try {
+                backend.cleanup();
+                logger.debug(`Backend '${id}' cleaned up`);
+            }
+            catch {
+                // Ignore errors during shutdown
+            }
+        }
+    }
+    /** Reset the registry (call after full shutdown). */
+    reset() {
+        this.backends.clear();
+        this.capabilityMap.clear();
+        this.services.clear();
+    }
+}
+export const ExtensionPoint = new ExtensionPointImpl();
+//# sourceMappingURL=ExtensionPoint.js.map

package/dist/Infrastructure/ExtensionPoint.js.map

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

package/dist/Infrastructure/LocalFileStorage.d.ts

@@ -0,0 +1,134 @@
+/**
+ * LocalFileStorage - Persistent model storage using the File System Access API
+ *
+ * Allows users to choose a real folder on their local filesystem for model
+ * storage. Models are saved as actual files (e.g. ~/ai-models/smollm2.gguf)
+ * that persist permanently — no browser eviction, no re-downloads.
+ *
+ * The directory handle is stored in IndexedDB (not cookies — handles are
+ * structured-cloneable objects that can't be serialized to strings).
+ *
+ * Browser support:
+ *   - Chrome 122+: Full support with persistent permissions ("Allow on every visit")
+ *   - Chrome 86-121: Supported but re-prompts for permission each session
+ *   - Edge: Same as Chrome (Chromium-based)
+ *   - Firefox/Safari: NOT supported — falls back to OPFS storage
+ *
+ * Usage:
+ *   const storage = new LocalFileStorage();
+ *   await storage.chooseDirectory();        // User picks a folder
+ *   await storage.saveModel('model-id', data);
+ *
+ *   // On return visit:
+ *   const restored = await storage.restoreDirectory();
+ *   if (restored) {
+ *     const data = await storage.loadModel('model-id');
+ *   }
+ */
+export declare class LocalFileStorage {
+    private dirHandle;
+    private _isReady;
+    private _hasStoredHandle;
+    /** Per-key write lock to prevent concurrent writes to the same file. */
+    private writeLocks;
+    /** Whether the File System Access API is available in this browser. */
+    static get isSupported(): boolean;
+    /**
+     * Get the stored directory name from localStorage (fast, synchronous).
+     * Available immediately on page load before IndexedDB restores the handle.
+     * Returns the folder name only (e.g. "ai-models"), not the full path.
+     */
+    static get storedDirectoryName(): string | null;
+    /** Whether the storage is ready for use (directory selected + permission granted). */
+    get isReady(): boolean;
+    /** Whether a handle was found in IndexedDB (even if permission isn't granted yet). */
+    get hasStoredHandle(): boolean;
+    /** The name of the chosen directory (for display in UI). */
+    get directoryName(): string | null;
+    /**
+     * Prompt the user to choose a directory for model storage.
+     * Opens the OS folder picker dialog.
+     * Stores the directory handle in IndexedDB for future sessions.
+     *
+     * @returns true if a directory was selected, false if cancelled
+     */
+    chooseDirectory(): Promise<boolean>;
+    /**
+     * Attempt to restore a previously chosen directory from IndexedDB.
+     *
+     * On Chrome 122+, if the user selected "Allow on every visit",
+     * permission is automatically granted without any prompt.
+     *
+     * @returns true if directory was restored and permission is granted.
+     *          false if no handle stored or permission not granted (UI
+     *          should show a "Re-authorize" button).
+     */
+    restoreDirectory(): Promise<boolean>;
+    /**
+     * Request readwrite permission on a previously stored handle.
+     * MUST be called from a user gesture (button click handler).
+     *
+     * @returns true if permission was granted
+     */
+    requestAccess(): Promise<boolean>;
+    /**
+     * Save model data to the local filesystem.
+     * Uses a per-key lock to prevent concurrent writes from corrupting files.
+     * @param key - Model identifier (used as filename)
+     * @param data - Model file data
+     */
+    saveModel(key: string, data: ArrayBuffer): Promise<void>;
+    /**
+     * Save model data from a ReadableStream to the local filesystem.
+     * Streams data directly to disk without buffering the entire file in memory.
+     * Uses a per-key lock to prevent concurrent writes from corrupting files.
+     * @param key - Model identifier (used as filename)
+     * @param stream - Readable stream of model data
+     */
+    saveModelFromStream(key: string, stream: ReadableStream<Uint8Array>): Promise<void>;
+    private _saveModelImpl;
+    private _saveStreamImpl;
+    /**
+     * Per-key write lock: ensures only one write operation per key at a time.
+     * Concurrent calls for the same key will be serialized.
+     */
+    private withWriteLock;
+    /**
+     * Load model data from the local filesystem.
+     * @param key - Model identifier
+     * @returns Model data, or null if not found
+     */
+    loadModel(key: string): Promise<ArrayBuffer | null>;
+    /**
+     * Check if a model file exists in local storage.
+     * @param key - Model identifier
+     */
+    hasModel(key: string): Promise<boolean>;
+    /**
+     * Delete a model file from local storage.
+     * @param key - Model identifier
+     */
+    deleteModel(key: string): Promise<void>;
+    /**
+     * Get file size without reading into memory.
+     * @param key - Model identifier
+     */
+    getFileSize(key: string): Promise<number | null>;
+    /**
+     * List all model files in the directory.
+     */
+    listModels(): Promise<Array<{
+        id: string;
+        sizeBytes: number;
+        lastModified: number;
+    }>>;
+    private openDB;
+    private storeHandle;
+    private retrieveHandle;
+    /**
+     * Sanitize a key for use as a filename.
+     * Keeps alphanumeric, dots, dashes, underscores. Replaces everything else.
+     */
+    private sanitizeFilename;
+}
+//# sourceMappingURL=LocalFileStorage.d.ts.map

package/dist/Infrastructure/LocalFileStorage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"LocalFileStorage.d.ts","sourceRoot":"","sources":["../../src/Infrastructure/LocalFileStorage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAoCH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,SAAS,CAA0C;IAC3D,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,gBAAgB,CAAS;IAEjC,wEAAwE;IACxE,OAAO,CAAC,UAAU,CAAyC;IAM3D,uEAAuE;IACvE,MAAM,KAAK,WAAW,IAAI,OAAO,CAEhC;IAED;;;;OAIG;IACH,MAAM,KAAK,mBAAmB,IAAI,MAAM,GAAG,IAAI,CAM9C;IAMD,sFAAsF;IACtF,IAAI,OAAO,IAAI,OAAO,CAErB;IAED,sFAAsF;IACtF,IAAI,eAAe,IAAI,OAAO,CAE7B;IAED,4DAA4D;IAC5D,IAAI,aAAa,IAAI,MAAM,GAAG,IAAI,CAEjC;IAMD;;;;;;OAMG;IACG,eAAe,IAAI,OAAO,CAAC,OAAO,CAAC;IAiCzC;;;;;;;;;OASG;IACG,gBAAgB,IAAI,OAAO,CAAC,OAAO,CAAC;IAkC1C;;;;;OAKG;IACG,aAAa,IAAI,OAAO,CAAC,OAAO,CAAC;IA0BvC;;;;;OAKG;IACG,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAI9D;;;;;;OAMG;IACG,mBAAmB,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,cAAc,CAAC,UAAU,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;YAI3E,cAAc;YAmBd,eAAe;IAwB7B;;;OAGG;YACW,aAAa;IAc3B;;;;OAIG;IACG,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC;IAczD;;;OAGG;IACG,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAY7C;;;OAGG;IACG,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAY7C;;;OAGG;IACG,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAatD;;OAEG;IACG,UAAU,IAAI,OAAO,CAAC,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;YAwB7E,MAAM;YAgBN,WAAW;YAiBX,cAAc;IAsB5B;;;OAGG;IACH,OAAO,CAAC,gBAAgB;CAGzB"}