plusui-native-core 0.1.101 → 0.1.103

package/Core/Features/API/Connect_API.ts

@@ -1,160 +1,76 @@
 /**
- * PlusUI Connect API - Custom User Channels
- * 
- * This is for user-defined channels generated by `plusui connect` tool.
- * Built-in features (window, clipboard, etc.) use direct methods only.
- * 
- * Usage:
- *   import { createChannel, connect } from '@plusui/api';
- *   
- *   // Create a custom channel
- *   const search = createChannel('search');
- *   search.emit({ query: 'test' });
- *   search.on((result) => { ... });
- *   
- *   // Or use connect directly
- *   connect.emit('myEvent', { data: 123 });
- *   connect.on('myEvent', (data) => { ... });
- * 
- * The `plusui connect` CLI tool scans your codebase for:
- *   - TypeScript: name.on() and name.emit()
- *   - C++: name.on() and name.emit()
- * And generates typed channel objects for both frontend and backend.
+ * PlusUI Connect API — Semantic Frontend ↔ Backend Communication
+ *
+ * ZERO CONFIG. SEMANTIC SYNTAX. ALL 5 PATTERNS.
+ *
+ * IMPORTANT: `connect` is for CUSTOM user-defined communication only!
+ * Built-in features (window, clipboard, app, etc.) use direct imports:
+ *   import plusui from 'plusui';
+ *   plusui.window.minimize();
+ *   plusui.clipboard.setText('hello');
+ *
+ * For custom communication, use `connect.namespace.method()`:
+ *
+ *   import { connect } from 'plusui';
+ *
+ *   // Request/Response — await a call to the backend
+ *   const user = await connect.user.fetch(123);
+ *
+ *   // Fire & Forget — one-way notification
+ *   connect.files.upload({ file: myFile });
+ *
+ *   // Event Listener — listen for backend events
+ *   connect.app.onNotify((msg) => console.log(msg));
+ *
+ *   // Register a handler — backend can call frontend
+ *   connect.ui.handlePrompt = async (data) => {
+ *     return await Dialog.confirm(data.msg);
+ *   };
+ *
+ * Then run `plusui connect` to generate typed bindings.
+ *
+ * Pattern detection is automatic:
+ *   - `await connect.x.y()` → CALL (Request/Response)
+ *   - `connect.x.onY(cb)` → EVENT (Subscribe)
+ *   - `connect.x.handleY = fn` → HANDLER (Backend calls frontend)
+ *   - `connect.x.y()` → FIRE (Simplex, one-way)
  */
 
-import { _client } from '../Connection/connect';
+import { connect, _client, createFeatureConnect } from '../Connection/connect';
+import type { FeatureConnect, ConnectionKind, ConnectionEnvelope } from '../Connection/connect';
 
 /**
- * Channel object returned by createChannel()
- * Mirrors the C++ Connect::Channel API
- */
-export interface Channel<T = unknown> {
-  /**
-   * Listen for messages on this channel
-   * @param callback - Function called when message is received
-   * @returns Unsubscribe function
-   */
-  on(callback: (data: T) => void): () => void;
-
-  /**
-   * Send a message on this channel
-   * @param data - Data to send
-   */
-  emit(data: T): void;
-
-  /**
-   * Channel name
-   */
-  readonly name: string;
-}
-
-/**
- * Create a named channel object
- * 
- * @param name - Channel name (must match backend)
- * @returns Channel object with .on() and .emit()
- * 
- * @example
- *   const download = createChannel<DownloadProgress>('download');
- *   download.emit({ url: 'https://example.com/file.zip' });
- *   download.on((progress) => console.log(progress.percent));
+ * connect — Semantic channel proxy
+ *
+ * Usage:
+ *   connect.namespace.method(...args)
+ *
+ * The proxy routes to the correct wire format automatically:
+ *   connect.user.fetch(123)         → _client.call('user.fetch', 123)
+ *   connect.app.onNotify(cb)        → _client.on('app.onNotify', cb)
+ *   connect.ui.handlePrompt = fn    → _client.handle('ui.handlePrompt', fn)
+ *   connect.system.minimize()       → _client.fire('system.minimize', {})
+ *
+ * Works dynamically even before running `plusui connect`.
+ * After running `plusui connect`, you get IDE autocomplete.
  */
-export function createChannel<T = unknown>(name: string): Channel<T> {
-  return {
-    name,
-    on: (callback: (data: T) => void): (() => void) => {
-      return _client.on<T>(name, callback);
-    },
-    emit: (data: T): void => {
-      _client.fire(name, data);
-    }
-  };
-}
+export { connect };
 
 /**
- * Direct connect API for custom channels
- * 
- * Use this for quick one-off events, or use createChannel() 
- * for typed, reusable channel objects.
+ * _client — Low-level connection client
+ *
+ * Direct access to the underlying client for advanced use cases.
+ * Prefer using `connect.namespace.method()` for normal communication.
  */
-export const connect = {
-  /**
-   * Send a message on a channel
-   * @param name - Channel name
-   * @param data - Data to send
-   */
-  emit: <T = unknown>(name: string, data: T): void => {
-    _client.fire(name, data);
-  },
-
-  /**
-   * Listen for messages on a channel
-   * @param name - Channel name
-   * @param callback - Function called when message is received
-   * @returns Unsubscribe function
-   */
-  on: <T = unknown>(name: string, callback: (data: T) => void): (() => void) => {
-    return _client.on<T>(name, callback);
-  },
-
-  /**
-   * Make a call and wait for response
-   * @param name - Channel name
-   * @param data - Request data
-   * @returns Promise with response
-   */
-  call: <TResponse = unknown, TRequest = unknown>(name: string, data: TRequest): Promise<TResponse> => {
-    return _client.call<TResponse, TRequest>(name, data);
-  },
-
-  /**
-   * Create a typed channel object
-   * @param name - Channel name
-   * @returns Channel object with .on() and .emit()
-   */
-  channel: <T = unknown>(name: string): Channel<T> => {
-    return createChannel<T>(name);
-  }
-};
+export { _client };
 
 /**
- * Feature-scoped connect
- * 
- * Creates a connect API that automatically prefixes all channel names
- * with a scope. Useful for organizing channels by feature.
- * 
- * @param scope - Feature scope (e.g., 'auth', 'data', 'ui')
- * @returns Scoped connect API
- * 
- * @example
- *   const authConnect = createFeatureConnect('auth');
- *   authConnect.emit('login', { user: 'john' });  // sends to 'auth.login'
- *   authConnect.on('logout', () => {});           // listens to 'auth.logout'
+ * createFeatureConnect — Scoped connect for framework internals
+ *
+ * Creates a connect API scoped to a feature namespace.
+ * Used internally by PlusUI features like window, clipboard, etc.
  */
-export function createFeatureConnect(scope: string) {
-  const scopedName = (name: string): string => {
-    const prefix = `${scope}.`;
-    if (name.startsWith(prefix)) return name;
-    return prefix + name;
-  };
-
-  return {
-    emit: <T = unknown>(name: string, data: T): void => {
-      _client.fire(scopedName(name), data);
-    },
-
-    on: <T = unknown>(name: string, callback: (data: T) => void): (() => void) => {
-      return _client.on<T>(scopedName(name), callback);
-    },
-
-    call: <TResponse = unknown, TRequest = unknown>(name: string, data: TRequest): Promise<TResponse> => {
-      return _client.call<TResponse, TRequest>(scopedName(name), data);
-    },
-
-    channel: <T = unknown>(name: string): Channel<T> => {
-      return createChannel<T>(scopedName(name));
-    }
-  };
-}
+export { createFeatureConnect };
 
+export type { FeatureConnect, ConnectionKind, ConnectionEnvelope };
 export default connect;

package/Core/Features/API/index.ts

@@ -14,7 +14,7 @@ export { fileDrop, formatFileSize, createDropZone } from './filedrop-api';
 export { menu } from './menu-api';
 export { gpu, GPUBufferUsage, GPUTextureUsage, GPUMapMode, GPUShaderStage, GPUColorWrite } from './webgpu-api';
 
-export { connect, createChannel, type Channel } from './Connect_API';
+export { connect } from './Connect_API';
 export { _client } from '../Connection/connect';
 
 export type { WindowSize, WindowPosition, WindowRect } from './window-api';
@@ -40,7 +40,7 @@ import { display } from './display-api';
 import { fileDrop, formatFileSize, createDropZone } from './filedrop-api';
 import { menu } from './menu-api';
 import { gpu, GPUBufferUsage, GPUTextureUsage, GPUMapMode, GPUShaderStage, GPUColorWrite } from './webgpu-api';
-import { connect, createChannel } from './Connect_API';
+import { connect } from './Connect_API';
 
 const plusui = {
   window,
@@ -58,7 +58,6 @@ const plusui = {
   menu,
   gpu,
   connect,
-  createChannel,
   formatFileSize,
   KeyCode,
   KeyMod,

package/Core/Features/Connection/README.md

@@ -1,66 +1,158 @@
-# PlusUI Connection
+# PlusUI Connect
 
-## Two methods. Five primitives. Same syntax.
+## Semantic syntax. Zero config. All 5 patterns.
 
 ```typescript
-// TypeScript
-myEvent.on((data) => { ... });
-myEvent.emit({ value: 123 });
+// TypeScript — just write what you mean
+const user = await connect.user.fetch(123);
+connect.app.onNotify((msg) => console.log(msg));
+connect.system.minimize();
 ```
 
 ```cpp
-// C++ (identical!)
-myEvent.on([&](const json& p) { ... });
-myEvent.emit({{"value", 123}});
+// C++ — identical semantic style
+connect::user.handleFetch = [](const json& p) -> json {
+    return database.getUser(p["id"]);
+};
+connect::app.notify({{"msg", "Hello!"}});
 ```
 
 ## Quick Start
 
-### 1. Write your code
+### 1. Write your code — anywhere
 
+**Frontend (TypeScript):**
 ```typescript
-// frontend/src/app.ts
-import { download } from '../Connections/connections.gen';
+import { connect } from 'plusui';
+
+// Call the backend and get a response
+const user = await connect.database.getUser(123);
 
-download.emit({ url: 'https://example.com/file.zip' });
-download.on((data) => {
-  progressBar.value = data.progress;
+// Listen for events from the backend
+connect.app.onNotify((msg) => {
+    toast.success(msg);
 });
+
+// Fire a one-way command
+connect.system.minimize();
 ```
 
+**Backend (C++):**
 ```cpp
-// main.cpp
+#include <plusui/plusui>
 #include "Connections/connections.gen.hpp"
 
-initChannels(connect);
+// Handle calls from the frontend
+connect::database.handleGetUser = [](const json& p) -> json {
+    auto id = p.get<int>();
+    return {{"name", "Dannan"}, {"id", id}};
+};
 
-download.on([&](const json& p) {
-  auto url = p.value("url", "");
-  download.emit({{"progress", 50}});
-});
+// Send events to the frontend
+connect::app.notify({{"msg", "Backend ready!"}});
+
+// Listen for one-way commands from the frontend
+connect::system.onMinimize = [](const json&) {
+    window.minimize();
+};
 ```
 
-### 2. Generate channels
+### 2. Generate bindings
 
 ```bash
 plusui connect
 ```
 
-Scans your `.ts`, `.tsx`, `.cpp`, `.hpp` files for `.on()` and `.emit()` calls, generates:
-- `Connections/connections.gen.ts`
-- `Connections/connections.gen.hpp`
+Scans your `.ts`, `.tsx`, `.cpp`, `.hpp` files for `connect.namespace.method()` patterns and generates:
+- `Connections/connections.gen.ts` — Typed semantic API for frontend
+- `Connections/connections.gen.hpp` — Typed semantic API for backend
+
+### 3. That's it.
+
+No schemas. No config files. No imports to manage (beyond `plusui`).
+Write your code, run `plusui connect`, done.
+
+---
+
+## The 5 Communication Patterns
+
+All 5 patterns work **bidirectionally** — frontend ↔ backend. The pattern used depends on which side is sending vs receiving.
+
+### 1. Request-Response (Call)
+
+A request is sent, processed, and a response is returned. Works both ways.
 
-## The 5 Primitives
+| Sender | Receiver |
+|--------|----------|
+| `await connect.user.fetch(123)` | `connect::user.handleFetch = [](json p) -> json { ... }` |
+| `connect.call("ui.prompt", data)` | `connect.ui.handlePrompt = async (data) => { ... }` |
 
-| Pattern | Direction | Use Case |
-|---------|-----------|----------|
-| **EVENT** | One way → | Notifications, commands |
-| **CALL** | Two ways ↔ | Request/response |
-| **STREAM** | Continuous → | Real-time updates |
-| **QUERY** | Many responses ↔↔↔ | Search, pagination |
-| **STATE** | Both ways ↕ | Synced values |
+### 2. Simplex (Fire & Forget)
+
+One-way message. Sender doesn't wait for a response. Works both ways.
+
+| Sender | Receiver |
+|--------|----------|
+| `connect.files.upload({ file })` | `connect::files.onUpload = [](json) { ... }` |
+| `connect::app.notify(data)` | `connect.app.onNotify((msg) => { ... })` |
+
+### 3. Publish-Subscribe (One-to-Many)
+
+Broadcast to multiple listeners. Works both ways.
+
+| Sender | Subscribers |
+|--------|-------------|
+| `connect::sensors.publishTemp(data)` | `connect.sensors.onTemp(cb)` |
+| `connect.auth.login(data)` | `connect::auth.onLogin = [](json) { ... }` |
+
+### 4. Full-Duplex (Bidirectional Stream)
+
+Both sides send and receive continuously. Works both ways.
+
+```typescript
+// Frontend: stream to backend
+connect.files.onChunk(chunk);
+connect.files.onProgress((p) => console.log(p));
+```
+
+```cpp
+// Backend: receive and stream back
+connect::files.onChunk = [](json chunk) { saveFile(chunk); };
+connect::files.progress({{"percent", 50}});
+```
 
-All handled with just `.on()` and `.emit()`.
+### 5. Half-Duplex (State Sync)
+
+Both sides can update, but one at a time. Works both ways.
+
+```typescript
+// Frontend updates and listens
+connect.settings.setTheme("dark");
+connect.settings.onThemeChange((t) => applyTheme(t));
+```
+
+```cpp
+// Backend updates and listens
+connect::settings.onSetTheme = [](json p) { applyNativeTheme(p); };
+connect::settings.themeChange({{"mode", "dark"}});
+```
+
+---
+
+## How Patterns Are Detected
+
+The `plusui connect` tool automatically infers the communication pattern from your code:
+
+| Your Code | Detected Pattern |
+|-----------|-----------------|
+| `await connect.x.y()` | **Call** (Request/Response) |
+| `connect.x.onY(callback)` | **Event** (Listener/Subscribe) |
+| `connect::x.handleY = fn` | **Call Handler** (Backend responds) |
+| `connect.x.y()` (no await) | **Fire** (Simplex/One-way) |
+
+You never need to specify the pattern. Just write natural, semantic code.
+
+---
 
 ## Generated Files
 
@@ -69,12 +161,17 @@ All handled with just `.on()` and `.emit()`.
 ```typescript
 import { _client } from 'plusui';
 
-export const download = {
-  on: <T = unknown>(cb: (data: T) => void) => _client.on('download', cb),
-  emit: (data: unknown) => _client.fire('download', data)
+export const user = {
+  fetch: <T = unknown>(...args: unknown[]) => _client.call<T>('user.fetch', args[0]),
 };
 
-export const CONNECT_CHANNELS = ['download'] as const;
+export const app = {
+  onNotify: <T = unknown>(cb: (data: T) => void) => _client.on<T>('app.onNotify', cb),
+};
+
+export const system = {
+  minimize: (...args: unknown[]) => _client.fire('system.minimize', args[0]),
+};
 ```
 
 ### C++ (`connections.gen.hpp`)
@@ -83,29 +180,56 @@ export const CONNECT_CHANNELS = ['download'] as const;
 #pragma once
 #include <plusui/plusui.hpp>
 
-namespace channels {
-  inline plusui::Connect* _connect = nullptr;
-  inline plusui::Connect::Channel download;
-}
+namespace connect {
+  inline plusui::Connect* _conn = nullptr;
 
-inline void initChannels(plusui::Connect& c) {
-  channels::_connect = &c;
-  channels::download = c.channel("download");
+  inline struct user_t {
+    std::function<nlohmann::json(const nlohmann::json&)> handleFetch;
+  } user;
+
+  inline struct app_t {
+    void notify(const nlohmann::json& p = nlohmann::json::object()) {
+      if (_conn) _conn->emit("app.notify", p);
+    }
+  } app;
+
+  inline struct system_t {
+    std::function<void(const nlohmann::json&)> onMinimize;
+  } system;
 }
 
-// Direct access (same as TypeScript)
-using channels::download;
+inline void initConnect(plusui::Connect& c) {
+  connect::_conn = &c;
+  c.onCall("user.handleFetch", [](const nlohmann::json& p) -> nlohmann::json {
+    if (connect::user.handleFetch) return connect::user.handleFetch(p);
+    return nlohmann::json::object();
+  });
+  c.on("system.onMinimize", [](const nlohmann::json& p) {
+    if (connect::system.onMinimize) connect::system.onMinimize(p);
+  });
+}
 ```
 
-## Built-in Channels
+---
+
+## Built-in Features
+
+Built-in features use direct imports from `plusui` — they're not custom channels:
 
 ```typescript
-import { win, clipboard, app } from 'plusui';
+import plusui from 'plusui';
 
-win.on((data) => console.log(data.width));
-clipboard.emit({ text: 'copied!' });
+plusui.window.minimize();
+plusui.clipboard.write('copied!');
 ```
 
-## That's it.
+## Legacy Support
+
+The old flat `name.on()` / `name.emit()` pattern still works for backward compatibility:
+
+```typescript
+download.on((data) => console.log(data.progress));
+download.emit({ url: 'https://example.com' });
+```
 
-No schemas. No configuration. Write `.on()` and `.emit()`, run `plusui connect`.
+These are detected alongside the new semantic patterns.