🚀 HyperFrame - Stop burning your CPU

The Ultimate Flutter Development Workbench with Built-in Developer Cockpit

HyperFrame is a blazing-fast Flutter development environment that runs mobile apps as native desktop apps with device frame simulation. Say goodbye to slow emulators and hello to instant hot reloads plus a powerful runtime debugging suite!

---

🎯 Why HyperFrame?

Traditional mobile development requires running heavy emulators that consume massive CPU resources and drain your battery. HyperFrame changes everything - and includes HyperConsole, your built-in developer cockpit for runtime debugging.

Key Benefits:

| Feature | Traditional Emulator | HyperFrame + HyperConsole | |---------|---------------------|---------------------------| | Speed | Slow startup (30s+) | Instant (< 5s) ⚡️ | | CPU Usage | 40-60% constant load | < 10% 🔋 | | Hot Reload | 2-5 seconds | < 1 second 🔥 | | API Testing | Need Postman | Built-in Network Tab 🌐 | | Cache Debug | Manual logging | Live Cache Inspector 💾 | | Navigation Debug | Manual tracking | Browser-like History 🧭 | | Battery Impact | Drains rapidly | Minimal usage 🌱 | | Multi-Device | One at a time | Switch instantly 📱 |

---

✨ Features

Core Development Experience

• ⚡️ Native Performance - 10x faster than Android Emulator
• 📱 Multi-Device Simulation - iPhone, Pixel, iPad in one click
• 🔋 Battery Saver - No heavy virtualization
• 🎨 Instant Theme Testing - Toggle dark/light mode instantly
• 📐 Responsive Layout Validation - Test different screen sizes live
• 🛠 Developer Experience - Hot reload in milliseconds

🔥 HyperConsole - Built-in Developer Cockpit

One tap. Five powerful tools. Zero external dependencies.

• 🌐 Network Tester - Full REST client with mock data generation
• 💾 Cache Inspector - View, search, and clear app cache in real-time
• 🎨 Theme & Device Tab - Instant theme preview + device information
• 🧭 Router Manager - Browser-like navigation with history & favorites ⭐
• 📊 Live Logger - Real-time filtered logs with search

📖 Full HyperConsole Documentation →

Architecture & Quality

• 🏗 Clean Architecture - Feature-first structure
• 🔄 Riverpod State Management - Type-safe, reactive state
• 🧭 GoRouter Navigation - Declarative routing with deep linking
• 🌍 Cross-Platform Desktop - Works on macOS, Windows, Linux
• 🎯 Zero Configuration - Just clone and run

---

🚦 Quick Start

Prerequisites

• Flutter 3.10+ installed
• macOS 10.14+ (or Windows 10+ / Linux Ubuntu 20.04+)
• Xcode Command Line Tools (macOS only)

Installation

# 1. Clone the repository
git clone https://github.com/aeTunga/HyperFrame.git
cd HyperFrame

# 2. Get dependencies
flutter pub get

# 3. Generate Riverpod code (REQUIRED - run after every git pull!)
dart run build_runner build --delete-conflicting-outputs

# 4. Run on macOS (or your desktop platform)
flutter run -d macos

🎯 Opening HyperConsole

After the app launches, look for the blue floating button in the bottom-left corner.

• Tap → Opens HyperConsole with 5 debug tabs
• Long Press + Drag → Repositions the button

---

🛠 HyperConsole Overview

The 5 Power Tabs

1️⃣ Network Tester

Test APIs without leaving your app. Full REST client with request history.

// Test your backend instantly
GET https://api.example.com/users/123
POST https://api.example.com/auth/login

Features: Live API testing, request history, mock user generation, custom headers, formatted JSON responses.

---

2️⃣ Cache Inspector

View and manipulate local storage in real-time. Debug persistence issues instantly.

// See all cached data
theme_mode → "dark"
user_token → "eyJhbGc..."
onboarding_complete → true

Features: View all cache, search filter, individual/bulk clear, type display, live updates.

---

3️⃣ Device & Theme Tab

Switch between light/dark/system themes without rebuilding. View device specs.

Features: Live theme switching, device information, safe area display, brightness control, real-time updates.

---

4️⃣ Router Manager ⭐ NEW

Browser-like navigation debugging with history, favorites, and manual route testing.

// Navigate to any route
/user/123?edit=true
/admin/dashboard

// Features: Back/Forward, History (last 20), Favorites (persistent)

Features: Current route display, manual navigation, back/forward buttons, history (last 20), favorites, quick access chips.

---

5️⃣ Logger Tab

Real-time application logs with filtering. Copy logs for bug reports.

Features: Live log stream, log levels (Info/Warning/Error), search filter, auto-scroll, copy logs, clear logs.

---

📖 Full HyperConsole Documentation →

---

📱 Switching Devices

Want to test on a different device? It's incredibly simple:

1. Use the Toolbar - Click the device selector in the top toolbar (when app is running)
2. Or Edit Code - Open lib/main.dart and uncomment your desired device:

// Line ~45 in lib/main.dart
defaultDevice: Devices.ios.iPhone16ProMax,          // Current (iPhone)
// defaultDevice: Devices.android.pixel6,           // Uncomment for Pixel 6
// defaultDevice: Devices.ios.iPad12InchGen4,       // Uncomment for iPad
// defaultDevice: Devices.android.samsungGalaxyS20, // Uncomment for Samsung

Available Devices:

• iOS: iPhone SE, 13 Mini, 13, 13 Pro Max, 16 Pro Max, iPad Pro 11", iPad 12.9"
• Android: Pixel 4/5/6, Samsung Galaxy S20/Note20/A50, OnePlus 8 Pro

---

💻 Code Examples

Using NetworkManager (Type-Safe Generics)

import 'package:hyperframe/core/network/network_manager.dart';
import 'package:hyperframe/core/network/http_method.dart';

final networkManager = NetworkManager();

// Type-safe GET request
final response = await networkManager.request<User>(
  '/users/123',
  method: HttpMethod.get,
  parser: (json) => User.fromJson(json),
);

// Handle result
response.when(
  success: (user) => print('Welcome ${user.name}!'),
  failure: (error) => print('Error: ${error.message}'),
);

// POST with body
final createResponse = await networkManager.request<User>(
  '/users',
  method: HttpMethod.post,
  data: {'name': 'John', 'email': 'john@example.com'},
  parser: (json) => User.fromJson(json),
);

Using CacheManager

import 'package:hyperframe/core/caching/cache_manager.dart';
import 'package:hyperframe/core/constants/cache_keys.dart';

final cacheManager = CacheManager();

// Store primitives
await cacheManager.setString(CacheKeys.userToken, 'abc123');
await cacheManager.setInt('user_id', 42);
await cacheManager.setBool('onboarding_complete', true);

// Store JSON objects
await cacheManager.setJson('user_profile', user.toJson());

// Retrieve data
final token = await cacheManager.getString(CacheKeys.userToken);
final profile = await cacheManager.getJson('user_profile');

// Check & remove
if (await cacheManager.containsKey(CacheKeys.userToken)) {
  await cacheManager.remove(CacheKeys.userToken);
}

// Clear all (use with caution!)
await cacheManager.clear();

Using Riverpod State Management

import 'package:flutter_riverpod/flutter_riverpod.dart';
import 'package:riverpod_annotation/riverpod_annotation.dart';

part 'my_controller.g.dart';

// Auto-generated provider with code generation
@riverpod
class Counter extends _$Counter {
  @override
  int build() => 0;

  void increment() => state++;
  void decrement() => state--;
}

// In your widget
class MyWidget extends ConsumerWidget {
  @override
  Widget build(BuildContext context, WidgetRef ref) {
    final count = ref.watch(counterProvider);
    
    return Text('Count: $count');
  }
}

Custom Logging for HyperConsole

import 'package:hyperframe/core/init/log_helper.dart';

class MyService {
  Future<void> fetchData() async {
    LogHelper.info('Starting data fetch...');
    
    try {
      final data = await api.getData();
      LogHelper.info('Fetched ${data.length} items');
    } catch (e, stackTrace) {
      LogHelper.error('Fetch failed', error: e, stackTrace: stackTrace);
    }
  }
}

---

📂 Project Structure

hyperframe/
├── lib/
│   ├── main.dart                          # Smart runner with platform detection
│   ├── app.dart                           # MaterialApp with routing
│   ├── core/
│   │   ├── console/                      # 🆕 HyperConsole Developer Cockpit
│   │   │   ├── widgets/
│   │   │   │   ├── tabs/
│   │   │   │   │   ├── network_tester_tab.dart
│   │   │   │   │   ├── cache_viewer_tab.dart
│   │   │   │   │   ├── device_theme_tab.dart
│   │   │   │   │   ├── router_tab.dart        # ⭐ Browser-like navigation
│   │   │   │   │   └── logger_tab.dart
│   │   │   │   ├── hyper_console_button.dart  # Floating access button
│   │   │   │   └── hyper_console_sheet.dart   # Bottom sheet container
│   │   │   └── models/
│   │   ├── router/                       # 🆕 GoRouter navigation
│   │   │   └── app_router.dart          # Declarative routing
│   │   ├── network/                      # 🆕 NetworkManager + Dio
│   │   │   ├── interceptors/            # Error & logging interceptors
│   │   │   ├── exceptions/              # Network exceptions
│   │   │   └── network_manager.dart     # Type-safe HTTP client
│   │   ├── caching/                      # 🆕 CacheManager
│   │   │   └── cache_manager.dart       # Persistent local storage
│   │   ├── theme/
│   │   │   ├── app_theme.dart           # Material 3 themes
│   │   │   └── theme_provider.dart      # Theme state manageme