From f529cc28877c624ae9e986a12d4e69df8bc15105 Mon Sep 17 00:00:00 2001 From: Cyrus Gray <144336577+graycyrus@users.noreply.github.com> Date: Tue, 3 Feb 2026 17:33:12 +0530 Subject: [PATCH] Update the claude docs for javascript branch (#29) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * chore: bump version to 0.20.0 [skip ci] * revert: remove automatic skill dependency installation system - Removed dependency installation loading state from SkillSetupWizard - Reverted SkillRuntime dependency checking and installation methods - Cleaned up dependency-related imports and event listeners - Documented complete implementation in skills/todo.md for future work The dependency installation system was causing unwanted loading states when configuring skills. All functionality has been properly reverted while preserving implementation details for future development. * Refactor SkillManagementPanel to conditionally show action buttons based on connection status - Added offline and setup-required states with informative messages - Updated SkillSetupModal to use connection status for setup vs. manage mode - Simplified mode logic for better UX and error handling in setup scenarios * Update CLAUDE.md with new features, state slices, and code quality tools - Document additions: Redux aiSlice, skillsSlice, teamSlice, and architecture updates - Add ESLint, Prettier integrations with Husky hooks and GitHub workflows - Update development commands from npm to yarn for consistency - Expand key user groups and revise target audiences - Include enhanced project structure, build outputs, and CI/CD updates * chore: add simulation function for deep link testing in development - Introduced a simulation function for deep links in the development environment to facilitate testing. - The function allows developers to simulate deep link URLs without affecting production behavior. * fix: resolve TypeScript compilation error and enhance skill session synchronization - Fix unused parameter error in SkillManager.getSkillLoadParams() by prefixing with underscore - Add support for session parameter passing in SkillRuntime.load() method - Implement skill reloading capability for post-authentication updates - Ensure proper connection status synchronization between skill setup and UI display 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude * fix: change skill button text from 'Configure' to 'Manage' for connected skills - Update SkillsGrid button text to dynamically show based on connection status - Connected skills now show 'Manage' button instead of 'Configure' - Provides clearer user indication of skill state - Improves UX for authenticated skills like Telegram 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude * refactor: update documentation, download system and code formatting improvements - Update Claude rules with improved project overview and command documentation - Enhance download screen with better architecture detection and formatting - Improve device detection utilities with multi-architecture support - Add skills system troubleshooting documentation - Code formatting improvements with better line breaks and spacing - Optimize GitHub release asset parsing for platform-specific downloads 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude * feat: implement QuickJS skill runtime integration - Added a new QuickJS skill runtime engine to manage skill execution within the application. - Introduced commands for skill management, including discovery, starting, stopping, and querying skill states. - Implemented a SQLite database bridge for each skill to handle data storage. - Enhanced the application structure with new modules for runtime management, skill instances, and manifest parsing. - Updated dependencies in Cargo.toml and Cargo.lock to support new features. * refactor: improve code readability and formatting in DownloadScreen and deviceDetection - Enhanced the button className formatting in DownloadScreen for better readability. - Reformatted the fetchLatestRelease and parseReleaseAssetsByArchitecture functions in deviceDetection for improved clarity and maintainability. - Utilized multiline formatting for complex conditions to enhance code structure. * feat: integrate Rust-native Socket.io client for persistent connections - Implemented a SocketManager in Rust to handle Socket.io connections, ensuring persistence across app backgrounding. - Updated SocketProvider to connect/disconnect using Rust-native methods in Tauri mode. - Enhanced Tauri event listeners for socket state changes and server events. - Refactored socket handling logic to differentiate between web and Tauri modes, improving maintainability and clarity. - Added new commands for connecting, disconnecting, and emitting events through the Rust socket. * refactor: remove Telegram login commands and related functionality - Deleted the startTelegramLogin and startTelegramLoginWithUrl functions from the Tauri commands. - Removed associated references in the Rust command module and utility file. - This cleanup simplifies the codebase by eliminating unused Telegram login features. * feat: add cron scheduling functionality for skills - Introduced a new CronScheduler to manage scheduled tasks for skills, allowing for cron expression parsing and execution. - Added a cron bridge to expose scheduling methods to skill contexts, enabling skills to register, unregister, and list cron schedules. - Updated the RuntimeEngine to initialize and manage the cron scheduler, ensuring it runs in the background. - Enhanced skill instances to support cron scheduling through a new BridgeDeps structure. - Updated dependencies in Cargo.toml and Cargo.lock to include the cron crate. * feat: add Android support and enhance dependencies - Introduced Android-specific build and run commands in package.json for Tauri. - Updated Cargo.toml to include OpenSSL for Android and adjusted reqwest for cross-platform TLS support. - Added new mobile capabilities configuration for Android and iOS. - Implemented a foreground service in the Android app to maintain the Rust backend process. - Added various Android resources including layouts, icons, and notification handling. - Updated Cargo.lock with new dependencies for improved functionality. * chore: update .gitignore and AndroidManifest.xml for deep link support - Added .kotlin and .cargo to .gitignore to exclude Kotlin and Cargo build artifacts. - Updated AndroidManifest.xml with comments for the deep link plugin, clarifying its auto-generated nature. * feat: enhance store configuration for development testing - Added functionality to auto-inject a JWT token from environment variables during development. - Implemented automatic onboarding for users once their profile is fetched, improving the testing experience. * feat: enhance socket connection handling and add Android logging support - Updated the Rust socket connection command to accept an optional URL parameter, allowing for dynamic backend URL configuration. - Integrated Android logging capabilities using the android_logger crate, ensuring logs are properly routed to logcat. - Improved error handling in the SocketManager to log connection errors and successful connections for better debugging. * feat: implement notification permission handling and enhance foreground service in Android - Added runtime permission request for POST_NOTIFICATIONS in MainActivity to comply with API 33+ requirements. - Updated RuntimeService to specify foreground service type for API 34+ compatibility. - Improved logging levels in the Rust backend for better debugging and monitoring of socket connections and skill discovery. * feat: integrate QuickJS skill management and service - Added QuickJS skill hooks for retrieving and managing QuickJS skills from Redux. - Implemented a QuickJS service to handle skill lifecycle, preferences, and IPC calls with the Rust backend. - Enhanced the skills state in Redux to include QuickJS skills, enabling better management and state tracking. - Updated the store configuration to persist QuickJS skills state across sessions. - Introduced new commands in the Rust backend for enabling/disabling skills and managing preferences. - Improved the SkillProvider to initialize the QuickJS service during app startup. * refactor: transition skill management to QuickJS runtime - Removed legacy skill catalog and loading logic, replacing it with QuickJS runtime integration for skill discovery and management. - Updated SkillProvider to utilize QuickJS for skill registration and lifecycle management. - Simplified skill data handling by directly invoking the Rust backend for skill operations. - Enhanced error handling and logging for skill loading processes. - Cleaned up unused interfaces and functions related to previous skill management methods. * refactor: remove unused skill commands and plugins - Deleted the skills command module and related functions to streamline the codebase. - Removed dependencies on the tauri-plugin-shell and other unused plugins from Cargo.toml and Cargo.lock. - Updated the authentication module by removing the exchange_token function and its associated structures. - Simplified the capabilities configuration by eliminating shell-related permissions. - Enhanced the runtime engine to support new JSON-RPC commands for skill data management. * feat: expose whitelisted environment values to skills - Added `platform.env(key)` function to retrieve whitelisted environment values for skills. - Implemented `get_skill_env` function to provide access to `BACKEND_URL` and `PLATFORM`. - Updated `get_backend_url` to check for `VITE_BACKEND_URL` before falling back to `BACKEND_URL`. - Enhanced the QuickJS runtime to support the new environment functionality. * feat: fix skills enable/disable flow, setup pipeline, and status derivation - Add SkillSetup struct to Rust manifest and include setup field in discovery response so the frontend knows which skills need setup - Map setup field in SkillProvider discoverSkills() - Fix SkillsGrid to use real hasSetup from manifest instead of hardcoding false - Add contextual Enable/Setup/Configure/Retry buttons in management modal - Add status indicator dots to compact skill table rows - Fix deriveConnectionStatus to return "connected" for ready skills with completed setup that don't push host state (e.g. cron-based skills) - Add select option renderer in SkillManagementPanel for non-boolean options - Add dotenvy crate to load .env file at Rust startup so env vars like VITE_BACKEND_URL are available to the runtime engine and skills Co-Authored-By: Claude Opus 4.5 * feat: add platform support for skills and enhance manifest handling - Introduced platform filtering for skills in the SkillManifest, allowing skills to specify supported platforms. - Updated QuickJSManifest and runtime engine to handle platform checks, ensuring skills are only loaded on compatible platforms. - Added new build and watch commands for skills in package.json to streamline development. - Enhanced the Rust backend to log unsupported skills based on platform restrictions. * feat: update skills submodule with TypeScript pipeline and test harness Co-Authored-By: Claude Opus 4.5 * feat: transition from QuickJS to V8 runtime for skill management - Replaced QuickJS with V8 (via deno_core) for improved JavaScript execution and WASM support. - Updated skill management logic to utilize the new V8 runtime, including changes to the RuntimeEngine and skill instance handling. - Enhanced manifest handling to support the new runtime and added platform compatibility checks. - Introduced new dependencies and updated Cargo.toml to reflect changes in the skill execution environment. - Refactored related modules and commands to align with the V8 integration, ensuring a seamless transition for skill operations. * refactor: clean up dead code in IdbStorage and enhance ops module - Removed unused `#[allow(dead_code)]` annotations from the IdbStorage struct and its methods to improve code clarity. - Introduced new timer and WebSocket state management structures in the ops module, laying groundwork for future enhancements. - Added timer and WebSocket operation functions, including `op_timer_start`, `op_timer_cancel`, and WebSocket connection handling, to support asynchronous operations. * feat: implement high-level TDLib service with V8 integration - Introduced a new `TdlibV8Service` to manage TDLib client instances using the V8 runtime. - Added a `MockTdClient` for development and testing, simulating TDLib responses for various queries. - Enhanced the bootstrap script to initialize and manage TDLib clients, including methods for sending queries and retrieving authentication states. - Updated the `mod.rs` file to include the new service module and improved documentation for clarity. - Refactored existing code to support the new TDLib integration, ensuring a seamless experience for skill management. * refactor: update V8 runtime integration and platform handling - Updated the V8 runtime integration to ensure it is only available on desktop platforms, with appropriate error handling for mobile. - Refactored the `SocketManager` and command implementations to conditionally include desktop-only features, enhancing clarity and maintainability. - Cleaned up the `Cargo.toml` to reflect the changes in V8 runtime availability and added relevant documentation. - Removed dead code related to mobile platform handling in the TDLib integration, ensuring a streamlined codebase. * chore: update skills submodule to latest commit - Updated the skills submodule to the latest commit (19a18e8), ensuring alignment with recent changes and improvements in the codebase. * refactor: transition from QuickJS to V8 runtime for skill management - Updated the skills submodule to the latest commit, reflecting the transition from QuickJS to V8 for improved JavaScript execution. - Refactored skill management logic to utilize the V8 runtime, including changes to the RuntimeEngine and skill instance handling. - Enhanced manifest handling to support the new runtime and updated platform compatibility checks. - Removed dead code related to QuickJS, ensuring a streamlined codebase. - Updated comments and documentation to reflect the changes in runtime integration. * feat: enhance logging and update timer operations in V8 integration - Added logging for skill discovery and manifest processing in the V8 runtime, improving traceability during skill management. - Updated timer operation functions to use new prefixed names (`op_ah_timer_start` and `op_ah_timer_cancel`) to avoid conflicts with deno_core built-ins. - Implemented a mechanism to load .env files from various locations, ensuring environment variables are available for configuration. - Enhanced the `get_backend_url` function to include debug logging for better visibility of the backend URL resolution process. * chore: update skills submodule to latest commit and enhance logging - Updated the skills submodule to the latest commit (54c40a1), ensuring alignment with recent changes. - Added console logging for skill manifests during discovery in the SkillsGrid component to improve debugging and traceability. * refactor: clean up and format code in DownloadScreen and SkillsGrid components - Improved code readability by formatting multi-line statements in the DownloadScreen and SkillsGrid components. - Removed unnecessary type imports in DownloadScreen for clarity. - Enhanced the structure of the SkillsGrid component by adjusting the layout of JSX elements for better maintainability. - Updated socketService to ensure consistent import order and improved logging in TauriSocket utility functions. * chore: update development script in package.json - Replaced the existing setup-python-sidecar script with a new dev:app script to streamline the development process for Tauri applications, enabling better debugging with RUST_BACKTRACE and RUST_LOG settings. * refactor: update load method to accept additional parameters - Modified the load method in SkillRuntime to accept an optional additionalParams argument, enhancing flexibility for skill loading. - Ensured compatibility by using a fallback to an empty object when additionalParams is not provided. * refactor: improve JSX structure in SkillsGrid component - Enhanced the formatting of the connection status indicator in the SkillsGrid component for better readability. - Adjusted the indentation and spacing to maintain consistent code style and improve maintainability. * docs: update CLAUDE.md with V8 runtime migration and Android support - Document complete V8 runtime transition from QuickJS with deno_core integration - Add comprehensive V8 Runtime System section covering core components and bridge system - Document Android platform support with RuntimeService and notification handling - Update Rust backend documentation with new runtime management commands - Add skills development commands and enhanced debugging options - Document platform differences between desktop V8 runtime and mobile limitations - Update Recent Changes section with major runtime transition details - Add Android-specific platform gotchas and socket management guidance - Reflect enhanced Socket.io integration with Rust-native client - Update Key Patterns to include V8 skills runtime and platform considerations 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --------- Co-authored-by: Steven Enamakel <31011319+senamakel@users.noreply.github.com> Co-authored-by: github-actions[bot] Co-authored-by: Steven Enamakel Co-authored-by: Claude --- CLAUDE.md | 111 +++++++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 102 insertions(+), 9 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index cbdcb16cc..88a8097ba 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -4,7 +4,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co ## Project Summary -Cross-platform crypto community communication platform built with **Tauri v2** (React 19 + Rust). Targets desktop (Windows, macOS) and mobile (Android, iOS). Features deep Telegram integration via MTProto, real-time Socket.io communication, and an MCP (Model Context Protocol) tool system for AI-driven Telegram interactions. +Cross-platform crypto community communication platform built with **Tauri v2** (React 19 + Rust). Targets desktop (Windows, macOS) and mobile (Android, iOS). Features deep Telegram integration via MTProto, real-time Socket.io communication, V8-based skill execution engine, and an MCP (Model Context Protocol) tool system for AI-driven Telegram interactions. ## App Theme & Design System @@ -48,6 +48,9 @@ yarn dev # Desktop dev with hot-reload (starts Vite + Tauri) yarn tauri dev +# Desktop dev with enhanced debugging (RUST_BACKTRACE and RUST_LOG enabled) +yarn dev:app + # Production build (TypeScript compile + Vite build + Tauri bundle) yarn tauri build @@ -64,6 +67,10 @@ yarn tauri android build yarn tauri ios dev yarn tauri ios build +# Skills development +yarn skills:build # Build skills in development mode +yarn skills:watch # Watch skills for changes + # Rust checks cargo check --manifest-path src-tauri/Cargo.toml cargo clippy --manifest-path src-tauri/Cargo.toml @@ -86,7 +93,7 @@ State lives in `src/store/` using Redux Toolkit slices: - **socketSlice** — connection status, socket ID - **telegramSlice** — connection/auth status, chats, messages, threads (selectively persisted; loading/error states excluded) - **aiSlice** — AI system state, memory management, session tracking -- **skillsSlice** — skills catalog, setup status, management state +- **skillsSlice** — skills catalog, setup status, management state, V8 runtime integration - **teamSlice** — team management, member invites, permissions Redux Persist stores auth and telegram state (storage backend is configurable; default uses localStorage). The telegram slice has a complex nested structure in `src/store/telegram/` with separate files for types, reducers, extraReducers, and thunks. @@ -101,7 +108,7 @@ Redux Persist stores auth and telegram state (storage backend is configurable; d ### Service Layer (Singletons) - **mtprotoService** (`src/services/mtprotoService.ts`) — Telegram MTProto client via `telegram` npm package. Session stored in Redux (`telegram.byUser[userId].sessionString`), not localStorage. Auto-retries FLOOD_WAIT up to 60s. -- **socketService** (`src/services/socketService.ts`) — Socket.io client. Auth token passed in socket `auth` object (not query string). Transports: polling first, then WebSocket. +- **socketService** (`src/services/socketService.ts`) — Socket.io client. Auth token passed in socket `auth` object (not query string). Transports: polling first, then WebSocket. Enhanced with Rust-native Socket.io client for persistent connections. - **apiClient** (`src/services/apiClient.ts`) — HTTP client for REST backend. ### MCP System (`src/lib/mcp/`) @@ -139,13 +146,59 @@ Key file: `src/utils/desktopDeepLinkListener.ts` (lazy-loaded in `main.tsx`). Us ### Rust Backend (`src-tauri/src/lib.rs`) -Minimal — two Tauri commands: +Enhanced Rust backend with comprehensive skill execution and runtime management: +**Core Commands:** - `greet` — demo command -- `exchange_token` — CORS-free HTTP POST to backend for token exchange +- `exchange_token` — CORS-free HTTP POST to backend for token exchange (desktop only) + +**Runtime Management:** +- `discover_skills` — V8 skill discovery and manifest parsing +- `enable_skill` / `disable_skill` — skill lifecycle management +- `get_skill_preferences` / `set_skill_preferences` — skill configuration +- `connect_to_socket` — Rust-native Socket.io connection +- `get_socket_status` — connection status monitoring + +**Android Support:** +- `RuntimeService` — background service for skill execution +- Notification permissions and foreground service management +- Android logging integration with logcat Deep link plugin registered at setup. `register_all()` called only on Windows/Linux (panics on macOS). +### V8 Runtime System (`src-tauri/src/runtime/`) + +Advanced JavaScript execution engine for skills using V8 (via deno_core): + +**Core Components:** +- `v8_engine.rs` — V8 JavaScript runtime initialization and management +- `v8_skill_instance.rs` — Individual skill execution contexts and lifecycle +- `skill_registry.rs` — Skill discovery, registration, and state management +- `manifest.rs` — Skill manifest parsing with platform compatibility checks +- `socket_manager.rs` — Persistent Socket.io connections with reconnection logic +- `cron_scheduler.rs` — Scheduled task execution for time-based skills +- `preferences.rs` — Skill configuration and settings persistence + +**Bridge System (`src-tauri/src/runtime/bridge/`):** +- `skills_bridge.rs` — Skill-to-skill communication and state sharing +- `tauri_bridge.rs` — Frontend-backend IPC and environment access +- `net.rs` — HTTP/fetch operations for skills +- `db.rs` — Database operations and storage management +- `store.rs` — Key-value storage for skill data +- `log_bridge.rs` — Structured logging from skills +- `cron_bridge.rs` — Cron job scheduling and management + +**TDLib Integration (`src-tauri/src/services/tdlib_v8/`):** +- `service.rs` — High-level TDLib client management with V8 integration +- `bootstrap.js` — V8 JavaScript bootstrap environment +- `ops/mod.rs` — Native operations for WebSocket, timers, and async handling +- `storage.rs` — Persistent storage for TDLib sessions and data + +**Platform Support:** +- Desktop platforms: Full V8 runtime with all features +- Mobile platforms: Error handling with feature availability checks +- Platform-specific skill filtering based on manifest declarations + ## Environment Variables Set in `.env` (Vite exposes `VITE_*` prefixed vars): @@ -162,9 +215,44 @@ Set in `.env` (Vite exposes `VITE_*` prefixed vars): Production defaults are in `src/utils/config.ts`. -## Recent Changes (Last 24 Hours) +## Recent Changes -Key updates from recent commits: +Key updates from recent commits (cd9ebcd to current): + +### Major Runtime Transition + +- **V8 Runtime Migration** (`99c20ea`, `0f6a092`): Complete transition from QuickJS to V8 + - Replaced QuickJS with V8 (via deno_core) for improved JavaScript execution and WASM support + - Enhanced skill management with V8 runtime including improved performance and compatibility + - New V8 skill instance handling with advanced execution contexts + - Updated dependencies and Cargo.toml to reflect V8 integration + - Platform compatibility checks and enhanced manifest handling + +### Android Platform Support + +- **Full Android Integration** (`ce06cfc`, `a2578b9`): Production-ready mobile platform support + - Complete Android project generation with MainActivity and RuntimeService + - Background service for persistent skill execution on Android + - Notification permission handling and foreground service management + - Android logging integration with logcat for better debugging + - Deep link support configuration in AndroidManifest.xml + +### Enhanced Socket & Runtime Management + +- **Rust-Native Socket.io Client** (`68d397e`): Persistent connection infrastructure + - Native Rust Socket.io implementation for improved reliability + - Enhanced socket connection handling with reconnection logic + - Dynamic backend URL configuration support + - Improved error handling and connection status monitoring + +### Skills System Improvements + +- **Advanced Skill Management** (`e841c86`, `719e6e5`): Enhanced skill lifecycle and configuration + - Skill setup pipeline with contextual Enable/Setup/Configure/Retry buttons + - Platform filtering for skills with manifest-based compatibility checks + - Enhanced skill status derivation and connection indicators + - Environment variable exposure to skills (whitelisted values) + - Improved skill discovery and manifest processing with logging ### Major Additions @@ -257,7 +345,7 @@ Key updates from recent commits: - **Code Quality**: ESLint and Prettier enforce code standards with Husky hooks. Use type-only imports (`import type`) and consolidate imports from same modules. - **No localStorage**: Avoid `localStorage` and `sessionStorage`; use Redux (and persist) for app state. Remove any direct usage when working on affected code. - **AI System Integration**: Use `src/lib/ai/` for memory management, constitution loading, entity queries, and session capture. AI providers abstracted through interface pattern. -- **Skills Management**: Skills loaded dynamically from local directory via Rust. Use `SkillProvider` for GitHub sync and `SkillsGrid` for management interface. +- **V8 Skills Runtime**: Skills execute in V8 JavaScript engine on desktop platforms. Use `SkillProvider` for GitHub sync, `SkillsGrid` for management interface, and Rust runtime commands for lifecycle management. Platform filtering ensures skills only run on supported platforms. - **Team Collaboration**: Team features in `src/components/settings/panels/Team*`. Use Redux `teamSlice` for state management and `teamApi` for backend operations. - **Device Detection**: Use `deviceDetection.ts` utilities for platform/architecture detection. Support multiple architectures per platform (x64, aarch64) with intelligent preference logic. - **GitHub Integration**: Fetch release assets via GitHub API (`fetchLatestRelease()`) and parse by architecture (`parseReleaseAssetsByArchitecture()`). Use Maps for efficient unique architecture tracking. @@ -268,14 +356,19 @@ Key updates from recent commits: - **Node polyfills**: Vite config (`vite.config.ts`) polyfills `buffer`, `process`, `util`, `os`, `crypto`, `stream` for the `telegram` package which requires Node APIs. - **Telegram IDs**: Use `big-integer` library, not native JS numbers (Telegram IDs exceed `Number.MAX_SAFE_INTEGER`). - **MCP tool files**: Each tool in `src/lib/mcp/telegram/tools/` exports a handler conforming to `TelegramMCPToolHandler` interface. Tool names are typed in `src/lib/mcp/telegram/types.ts`. -- **Tauri IPC**: Frontend calls Rust via `invoke()` from `@tauri-apps/api/core`. Rust commands are registered in `generate_handler![]` macro. +- **Tauri IPC**: Frontend calls Rust via `invoke()` from `@tauri-apps/api/core`. Rust commands are registered in `generate_handler![]` macro. Enhanced with runtime management commands for V8 skill execution and Socket.io integration. - **CORS workaround**: External HTTP requests from the WebView hit CORS. Use Rust `reqwest` via Tauri commands instead of browser `fetch()`. - **Hash Routing**: Uses HashRouter for desktop app compatibility and deep link handling. - **Integration Libraries**: Each integration (Telegram, future Gmail, etc.) lives under `src/lib//` with its own `state/`, `services/`, `api/` subdirectories. Domain-specific services belong in the integration folder, not in `src/services/` (which holds only cross-cutting services like socketService, apiClient). - **Unit Tests**: All unit tests live in `__tests__/` folders co-located with the code they test. Use Jest with TypeScript support. +- **Runtime Platform Differences**: V8 runtime is desktop-only. Mobile platforms use feature detection and graceful degradation. Skills with platform restrictions are filtered during discovery. +- **Socket Management**: Rust-native Socket.io client provides persistent connections with automatic reconnection. Use `connect_to_socket` command instead of frontend-only socket connections for reliability. ## Platform Gotchas - **macOS deep links**: Require `.app` bundle (not `tauri dev`). Clear WebKit caches when debugging stale content: `rm -rf ~/Library/WebKit/com.alphahuman.app ~/Library/Caches/com.alphahuman.app` - **Cargo caching**: May serve stale frontend assets on incremental builds. Run `cargo clean --manifest-path src-tauri/Cargo.toml` if the app shows outdated UI. - **`window.__TAURI__`**: Not available at module load time. Use dynamic `import()` and try/catch for Tauri plugin calls. +- **Android background services**: RuntimeService requires notification permissions (API 33+) and foreground service type specification (API 34+). Use Android logging (`android_logger`) for debug output in logcat. +- **V8 runtime limitations**: V8 engine is desktop-only. Android skills should use lightweight alternatives or server-side execution patterns. +- **Socket connections**: Persistent Socket.io connections via Rust backend work better than WebView-based connections on mobile platforms.