plusui-native-core 0.1.55 → 0.1.57

package/Core/Features/Connection/ARCHITECTURE.md

@@ -1,369 +0,0 @@
-# Connection Feature Architecture
-
-## 🏗️ System Overview
-
-```
-┌─────────────────────────────────────────────────────────────────┐
-│                     PlusUI Connection Feature                    │
-│               Unified Frontend ↔ Backend Communication            │
-└─────────────────────────────────────────────────────────────────┘
-
-┌──────────────────┐                           ┌──────────────────┐
-│   Frontend (TS)  │                           │  Backend (C++)   │
-│                  │                           │                  │
-│  ┌────────────┐  │                           │  ┌────────────┐  │
-│  │  connect.* │  │                           │  │  Bindings  │  │
-│  │    API     │  │                           │  │   Class    │  │
-│  └─────┬──────┘  │                           │  └─────┬──────┘  │
-│        │         │                           │        │         │
-│  ┌─────▼──────┐  │    ┌─────────────┐        │  ┌─────▼──────┐  │
-│  │Connection  │◄─┼───►│  WebView2   │◄───────┼─►│Connection  │  │
-│  │  Client    │  │    │  IPC Layer  │        │  │  Protocol  │  │
-│  └────────────┘  │    └─────────────┘        │  └────────────┘  │
-│                  │                           │                  │
-└──────────────────┘                           └──────────────────┘
-
-                    ┌─────────────────┐
-                    │  Schema File    │
-                    │ connection.     │
-                    │   schema        │
-                    └────────┬────────┘
-                             │
-                    ┌────────▼────────┐
-                    │    Bindgen      │
-                    │   Generator     │
-                    └────────┬────────┘
-                             │
-                ┌────────────┴────────────┐
-                │                         │
-         ┌──────▼─────┐           ┌──────▼──────┐
-         │bindings.ts │           │bindings.hpp │
-         │(Generated) │           │ (Generated) │
-         └────────────┘           └─────────────┘
-```
-
-## 📊 Communication Flow
-
-### CALL Pattern (Request/Response)
-```
-Frontend                    Backend
-   │                           │
-   │──[1] call(name, args)────►│
-   │                           │
-   │                     [2] handle_*
-   │                           │
-   │◄──[3] result ─────────────│
-   │                           │
-```
-
-### FIRE Pattern (One-way)
-```
-Frontend                    Backend
-   │                           │
-   │──[1] fire(name, args)────►│
-   │                           │
-   │                     [2] handle_*
-   │                           │
-   │        (no response)      │
-```
-
-### EVENT Pattern (Backend → Frontend)
-```
-Frontend                    Backend
-   │                           │
-   │  [1] on(name, callback)   │
-   │                           │
-   │                           │ [2] emit_*
-   │◄──[3] event data ─────────│
-   │                           │
-   │  [4] callback(data)       │
-```
-
-### STREAM Pattern (Continuous Data)
-```
-Frontend                    Backend
-   │                           │
-   │ [1] stream.subscribe(cb)  │
-   │                           │
-   │                           │ [2] emit_* (repeated)
-   │◄──[3] data ───────────────│
-   │◄──[4] data ───────────────│
-   │◄──[5] data ───────────────│
-   │                           │
-```
-
-### CHANNEL Pattern (Bidirectional Pub/Sub)
-```
-Frontend                    Backend
-   │                           │
-   │──[1] channel.publish()───►│ [2] handle_*_publish
-   │                           │
-   │ [3] channel.subscribe()   │
-   │                           │
-   │◄──[4] emit_* ─────────────│
-   │                           │
-```
-
-## 🔄 Build & Generation Flow
-
-```
-1. Developer writes schema
-   └─► connection.schema
-
-2. Run connect generator tool
-   └─► node Tools/plusui-connector/src/connect.js
-
-3. Parser reads schema
-   └─► Parses connect definitions
-   └─► Validates syntax
-   └─► Creates method definitions
-
-4. Generator creates TypeScript
-   └─► Type definitions (GreetIn, GreetOut, etc.)
-   └─► connect.* API functions
-   └─► Typed callbacks
-
-5. Generator creates C++
-   └─► Struct definitions with JSON converters
-   └─► Virtual handler methods
-   └─► Emit helper methods
-   └─► Message dispatcher
-
-6. Files written
-   └─► Core/Features/Connection/generated/bindings.ts
-   └─► Core/Features/Connection/generated/bindings.hpp
-```
-
-## 📦 Component Architecture
-
-### TypeScript Side
-
-```
-┌──────────────────────────────────────┐
-│         Generated API (bindings.ts)   │
-│  ┌────────────────────────────────┐  │
-│  │  export const connect = {      │  │
-│  │    greet: (args) => ...,       │  │
-│  │    onResize: (cb) => ...,      │  │
-│  │    cpuUsage: { subscribe },    │  │
-│  │    logBus: { subscribe, pub }, │  │
-│  │  }                             │  │
-│  └────────────┬───────────────────┘  │
-└───────────────┼──────────────────────┘
-                │ uses
-                ▼
-┌──────────────────────────────────────┐
-│      Core Connection (connection.ts)  │
-│  ┌────────────────────────────────┐  │
-│  │  class ConnectionClient {      │  │
-│  │    call(name, args)            │  │
-│  │    fire(name, args)            │  │
-│  │    on(name, callback)          │  │
-│  │    stream(name)                │  │
-│  │    channel(name)               │  │
-│  │  }                             │  │
-│  └────────────┬───────────────────┘  │
-└───────────────┼──────────────────────┘
-                │ sends/receives
-                ▼
-┌──────────────────────────────────────┐
-│          Message Protocol             │
-│  {                                    │
-│    kind: "call" | "fire" | ...,      │
-│    id: "...",                         │
-│    name: "methodName",                │
-│    payload: { ... }                   │
-│  }                                    │
-└──────────────────────────────────────┘
-```
-
-### C++ Side
-
-```
-┌──────────────────────────────────────┐
-│       User Implementation             │
-│  ┌────────────────────────────────┐  │
-│  │  class MyApp : public          │  │
-│  │    plusui::connect::Bindings   │  │
-│  │  {                             │  │
-│  │    GreetOut handle_greet(...)  │  │
-│  │    void handle_log(...)        │  │
-│  │                                │  │
-│  │    void emitUpdate() {         │  │
-│  │      emit_onResize({...});     │  │
-│  │    }                           │  │
-│  │  }                             │  │
-│  └────────────┬───────────────────┘  │
-└───────────────┼──────────────────────┘
-                │ inherits
-                ▼
-┌──────────────────────────────────────┐
-│    Generated Base (bindings.hpp)      │
-│  ┌────────────────────────────────┐  │
-│  │  class Bindings : public       │  │
-│  │         Connection {           │  │
-│  │                                │  │
-│  │  // Virtual handlers           │  │
-│  │  virtual GreetOut handle_*     │  │
-│  │                                │  │
-│  │  // Emit methods               │  │
-│  │  void emit_onResize(...)       │  │
-│  │                                │  │
-│  │  // Message dispatcher         │  │
-│  │  void handleMessage(Envelope)  │  │
-│  │  }                             │  │
-│  └────────────┬───────────────────┘  │
-└───────────────┼──────────────────────┘
-                │ uses
-                ▼
-┌──────────────────────────────────────┐
-│      Core Connect (connect.hpp) │
-│  ┌────────────────────────────────┐  │
-│  │  class Connection {            │  │
-│  │    void send(Envelope)         │  │
-│  │    void call(...)              │  │
-│  │    void fire(...)              │  │
-│  │    void event(...)             │  │
-│  │  }                             │  │
-│  └────────────────────────────────┘  │
-└──────────────────────────────────────┘
-```
-
-## 🔑 Key Design Decisions
-
-### 1. Schema-Driven
-- **Why**: Single source of truth, prevents TS/C++ drift
-- **Benefit**: Auto-generated types, less manual work
-
-### 2. Strongly Typed
-- **Why**: Catch errors at compile time
-- **Benefit**: Better IDE support, safer code
-
-### 3. Pattern-Based
-- **Why**: Different use cases need different semantics
-- **Benefit**: Clear intent, optimized for each pattern
-
-### 4. Code Generation
-- **Why**: Boilerplate is tedious and error-prone
-- **Benefit**: Consistent, maintainable, fast development
-
-### 5. Struct-Based (not JSON)
-- **Why**: Type safety in C++
-- **Benefit**: Compiler checks, clear interfaces
-
-## 🎯 Design Principles
-
-1. **Simple Developer Experience**
-   - Minimal boilerplate
-   - Intuitive API
-   - Clear patterns
-
-2. **Type Safety**
-   - End-to-end type checking
-   - Auto-generated types
-   - Compile-time validation
-
-3. **Unified System**
-   - Single API for all patterns
-   - Consistent naming
-   - One import
-
-4. **Framework Agnostic**
-   - Works with React, Vue, Svelte
-   - No framework lock-in
-   - Plain TypeScript/JavaScript
-
-5. **Performance**
-   - Minimal overhead
-   - Efficient serialization
-   - Direct dispatch
-
-## 📐 Message Protocol
-
-### Envelope Structure
-```typescript
-{
-  kind: "call" | "fire" | "result" | "event" | "stream" | 
-        "sub" | "unsub" | "publish" | "error",
-  id?: string,          // Request ID (for calls)
-  name: string,         // Method/event name
-  payload: unknown,     // Data
-  error?: string        // Error message (if kind="error")
-}
-```
-
-### Message Kinds
-- **call**: Request (needs response)
-- **fire**: One-way command
-- **result**: Response to call
-- **event**: Backend notification
-- **stream**: Continuous data
-- **sub**: Subscribe to stream
-- **unsub**: Unsubscribe from stream
-- **publish**: Channel message
-- **error**: Error response
-
-## 🔒 Type Safety Flow
-
-```
-Schema Definition
-      ↓
-   Bindgen
-      ↓
-   ┌──────────────┐
-   │ TypeScript   │
-   │  - GreetIn   │
-   │  - GreetOut  │
-   └──────────────┘
-      ↓
-Frontend Code
-await connect.greet({ name: "..." })
-                     ↑ Type checked!
-                     ↓
-              { message: "..." }
-               ↑ Type checked!
-```
-
-```
-Schema Definition
-      ↓
-   Bindgen
-      ↓
-   ┌──────────────┐
-   │    C++       │
-   │  - GreetIn   │
-   │  - GreetOut  │
-   └──────────────┘
-      ↓
-Backend Code
-GreetOut handle_greet(const GreetIn& args)
-         ↑ Type checked!
-return { "Hello" }
-       ↑ Type checked!
-```
-
-## 🚀 Performance Characteristics
-
-- **Call latency**: ~1-2ms (depends on WebView2)
-- **Fire latency**: <1ms (fire-and-forget)
-- **Event dispatch**: <0.1ms (in-process)
-- **Serialization**: O(n) for payload size
-- **Memory**: Minimal (shared memory for IPC)
-
-## 🔧 Extension Points
-
-Future enhancements:
-- State synchronization (synced properties)
-- Binary protocol option (faster than JSON)
-- Compression for large payloads
-- Message batching
-- Request cancellation
-- Middleware/interceptors
-- RPC versioning
-
----
-
-**See Also:**
-- [README.md](README.md) - Complete guide
-- [QUICK_REFERENCE.md](QUICK_REFERENCE.md) - Cheat sheet
-- [MIGRATION.md](MIGRATION.md) - Migration from old system

package/Core/Features/Connection/examples/simple_tags_example.hpp

@@ -1,130 +0,0 @@
-/**
- * Example: Simple Tag-Based Connection (C++ Backend)
- * 
- * No schema file needed! Just tag your methods and bindgen does the rest.
- */
-
-#pragma once
-#include <plusui/connect.hpp>
-#include <string>
-
-namespace example {
-
-class SimpleApp : public plusui::Connect {
-public:
-  
-  // ============================================
-  // CONNECT_CALL: Request/Response
-  // Frontend can await the result
-  // ============================================
-  
-  // Simple call with one parameter
-  CONNECT_CALL(greet, std::string, std::string name)
-  std::string greet(const std::string& name) {
-    return "Hello, " + name + "!";
-  }
-  
-  // Call with multiple parameters → returns object
-  CONNECT_CALL(calculate, double, double a, double b)
-  double calculate(double a, double b) {
-    return a + b;
-  }
-  
-  // Call with complex return (auto-generates struct)
-  CONNECT_CALL(getUser, {int id, std::string name, std::string email}, int userId)
-  auto getUser(int userId) {
-    struct Result { int id; std::string name; std::string email; };
-    return Result{ userId, "John Doe", "john@example.com" };
-  }
-
-  // ============================================
-  // CONNECT_FIRE: One-way to Backend
-  // No response expected
-  // ============================================
-  
-  CONNECT_FIRE(minimize, void)
-  void minimize() {
-    // Minimize window
-    std::cout << "Minimizing..." << std::endl;
-  }
-  
-  CONNECT_FIRE(log, void, std::string level, std::string message)
-  void log(const std::string& level, const std::string& message) {
-    std::cout << "[" << level << "] " << message << std::endl;
-  }
-
-  // ============================================
-  // CONNECT_EVENT: Backend → Frontend
-  // Backend emits, frontend listens
-  // ============================================
-  
-  CONNECT_EVENT(onResize, int width, int height)
-  void emitResize(int width, int height) {
-    // Auto-generated emit method
-    emit_onResize(width, height);
-  }
-  
-  CONNECT_EVENT(onFileDrop, std::vector<std::string> files)
-  void emitFileDrop(const std::vector<std::string>& files) {
-    emit_onFileDrop(files);
-  }
-
-  // ============================================
-  // CONNECT_STREAM: Continuous Data
-  // Backend streams, frontend subscribes
-  // ============================================
-  
-  CONNECT_STREAM(cpuUsage, double percent)
-  void startMonitoring() {
-    // Stream CPU usage continuously
-    std::thread([this]() {
-      while (running) {
-        double cpu = getCpuUsage();
-        emit_cpuUsage(cpu);
-        std::this_thread::sleep_for(std::chrono::seconds(1));
-      }
-    }).detach();
-  }
-
-  // ============================================
-  // CONNECT_CHANNEL: Bidirectional
-  // Both sides can send and receive
-  // ============================================
-  
-  CONNECT_CHANNEL(logBus, std::string level, std::string line)
-  
-  // Receive from frontend
-  void onLogFromFrontend(const std::string& level, const std::string& line) {
-    std::cout << "[Frontend] " << level << ": " << line << std::endl;
-  }
-  
-  // Send to frontend
-  void sendLogToFrontend(const std::string& level, const std::string& line) {
-    emit_logBus(level, line);
-  }
-
-private:
-  bool running = true;
-  
-  double getCpuUsage() {
-    return 50.0 + (rand() % 30);
-  }
-};
-
-} // namespace example
-
-/**
- * This example shows how simple it is:
- * 
- * 1. Tag your methods with CONNECT_* macros
- * 2. Run: npm run bindgen
- * 3. Use in TypeScript:
- * 
- *    const result = await connect.greet({ name: 'World' });
- *    connect.minimize();
- *    connect.onResize((w, h) => updateUI(w, h));
- *    connect.cpuUsage.subscribe((cpu) => showCpu(cpu));
- *    connect.logBus.publish({ level: 'info', line: 'msg' });
- * 
- * That's it! No separate schema file, no manual typing.
- */