bps-kit 1.0.1 → 1.0.3

package/templates/vault/robius-app-architecture/SKILL.md

@@ -1,328 +0,0 @@
----
-name: robius-app-architecture
-description: |
-  CRITICAL: Use for Robius app architecture patterns. Triggers on:
-  Tokio, async, submit_async_request, 异步, 架构,
-  SignalToUI, Cx::post_action, worker task,
-  app structure, MatchEvent, handle_startup
----
-
-# Robius App Architecture Skill
-
-Best practices for structuring Makepad applications based on the Robrix and Moly codebases - production applications built with Makepad and Robius framework.
-
-**Source codebases:**
-- **Robrix**: Matrix chat client - complex sync/async with background subscriptions
-- **Moly**: AI chat application - cross-platform (native + WASM) with streaming APIs
-
-## Triggers
-
-Use this skill when:
-- Building a Makepad application with async backend integration
-- Designing sync/async communication patterns in Makepad
-- Structuring a Robius-style application
-- Keywords: robrix, robius, makepad app structure, async makepad, tokio makepad
-
-## Production Patterns
-
-For production-ready async patterns, see the `_base/` directory:
-
-| Pattern | Description |
-|---------|-------------|
-| 08-async-loading | Async data loading with loading states |
-| 09-streaming-results | Incremental results with SignalToUI |
-| 13-tokio-integration | Full tokio runtime integration |
-
-## Core Architecture Pattern
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│                     UI Thread (Makepad)                     │
-│  ┌─────────┐     ┌──────────┐     ┌──────────────────────┐ │
-│  │   App   │────▶│ WidgetRef │────▶│ Widget Tree (View)  │ │
-│  │ State   │     │    ui     │     │ Scope::with_data()  │ │
-│  └────┬────┘     └──────────┘     └──────────────────────┘ │
-│       │                                                     │
-│       │ submit_async_request()                              │
-│       ▼                                                     │
-│  ┌─────────────────┐          ┌─────────────────────────┐  │
-│  │ REQUEST_SENDER  │─────────▶│  Crossbeam SegQueue     │  │
-│  │ (MPSC Channel)  │          │  (Lock-free Updates)    │  │
-│  └─────────────────┘          └─────────────────────────┘  │
-└───────────────────────────────────┬─────────────────────────┘
-                                    │
-                    SignalToUI::set_ui_signal()
-                                    │
-┌───────────────────────────────────┴─────────────────────────┐
-│                   Tokio Runtime (Async)                      │
-│  ┌──────────────────────────────────────────────────────┐   │
-│  │           worker_task (Request Handler)               │   │
-│  │  - Receives Request from UI                           │   │
-│  │  - Spawns async tasks per request                     │   │
-│  │  - Posts actions back via Cx::post_action()           │   │
-│  └──────────────────────────────────────────────────────┘   │
-│  ┌──────────────────────────────────────────────────────┐   │
-│  │         Per-Item Subscriber Tasks                     │   │
-│  │  - Listens to external data stream                    │   │
-│  │  - Sends Update via crossbeam channel                 │   │
-│  │  - Calls SignalToUI::set_ui_signal() to wake UI       │   │
-│  └──────────────────────────────────────────────────────┘   │
-└─────────────────────────────────────────────────────────────┘
-```
-
-## App Structure
-
-### Top-Level App Definition
-
-```rust
-use makepad_widgets::*;
-
-live_design! {
-    use link::theme::*;
-    use link::widgets::*;
-
-    App = {{App}} {
-        ui: <Root>{
-            main_window = <Window> {
-                window: {inner_size: vec2(1280, 800), title: "MyApp"},
-                body = {
-                    // Main content here
-                }
-            }
-        }
-    }
-}
-
-app_main!(App);
-
-#[derive(Live)]
-pub struct App {
-    #[live] ui: WidgetRef,
-    #[rust] app_state: AppState,
-}
-
-impl LiveRegister for App {
-    fn live_register(cx: &mut Cx) {
-        // Order matters: register base widgets first
-        makepad_widgets::live_design(cx);
-        // Then shared/common widgets
-        crate::shared::live_design(cx);
-        // Then feature modules
-        crate::home::live_design(cx);
-    }
-}
-
-impl LiveHook for App {
-    fn after_new_from_doc(&mut self, cx: &mut Cx) {
-        // One-time initialization after widget tree is created
-    }
-}
-```
-
-### AppMain Implementation
-
-```rust
-impl AppMain for App {
-    fn handle_event(&mut self, cx: &mut Cx, event: &Event) {
-        // Forward to MatchEvent trait
-        self.match_event(cx, event);
-
-        // Pass AppState through widget tree via Scope
-        let scope = &mut Scope::with_data(&mut self.app_state);
-        self.ui.handle_event(cx, event, scope);
-    }
-}
-```
-
-## Tokio Runtime Integration
-
-### Static Runtime Initialization
-
-```rust
-use std::sync::Mutex;
-use tokio::sync::mpsc::{UnboundedReceiver, UnboundedSender};
-
-static TOKIO_RUNTIME: Mutex<Option<tokio::runtime::Runtime>> = Mutex::new(None);
-static REQUEST_SENDER: Mutex<Option<UnboundedSender<AppRequest>>> = Mutex::new(None);
-
-pub fn start_async_runtime() -> Result<tokio::runtime::Handle> {
-    let (request_sender, request_receiver) = tokio::sync::mpsc::unbounded_channel();
-
-    let rt_handle = TOKIO_RUNTIME.lock().unwrap()
-        .get_or_insert_with(|| {
-            tokio::runtime::Runtime::new()
-                .expect("Failed to create Tokio runtime")
-        })
-        .handle()
-        .clone();
-
-    // Store sender for UI thread to use
-    *REQUEST_SENDER.lock().unwrap() = Some(request_sender);
-
-    // Spawn the main worker task
-    rt_handle.spawn(worker_task(request_receiver));
-
-    Ok(rt_handle)
-}
-```
-
-### Request Submission Pattern
-
-```rust
-pub enum AppRequest {
-    FetchData { id: String },
-    SendMessage { content: String },
-    // ... other request types
-}
-
-/// Submit a request from UI thread to async runtime
-pub fn submit_async_request(req: AppRequest) {
-    if let Some(sender) = REQUEST_SENDER.lock().unwrap().as_ref() {
-        sender.send(req)
-            .expect("BUG: worker task receiver has died!");
-    }
-}
-```
-
-### Worker Task Pattern
-
-```rust
-async fn worker_task(mut request_receiver: UnboundedReceiver<AppRequest>) -> Result<()> {
-    while let Some(request) = request_receiver.recv().await {
-        match request {
-            AppRequest::FetchData { id } => {
-                // Spawn a new task for each request
-                let _task = tokio::spawn(async move {
-                    let result = fetch_data(&id).await;
-                    // Post result back to UI thread
-                    Cx::post_action(DataFetchedAction { id, result });
-                });
-            }
-            AppRequest::SendMessage { content } => {
-                let _task = tokio::spawn(async move {
-                    match send_message(&content).await {
-                        Ok(()) => Cx::post_action(MessageSentAction::Success),
-                        Err(e) => Cx::post_action(MessageSentAction::Failed(e)),
-                    }
-                });
-            }
-        }
-    }
-    Ok(())
-}
-```
-
-## Lock-Free Update Queue Pattern
-
-For high-frequency updates from background tasks:
-
-```rust
-use crossbeam_queue::SegQueue;
-use makepad_widgets::SignalToUI;
-
-pub enum DataUpdate {
-    NewItem { item: Item },
-    ItemChanged { id: String, changes: Changes },
-    Status { message: String },
-}
-
-static PENDING_UPDATES: SegQueue<DataUpdate> = SegQueue::new();
-
-/// Called from background async tasks
-pub fn enqueue_update(update: DataUpdate) {
-    PENDING_UPDATES.push(update);
-    SignalToUI::set_ui_signal();  // Wake UI thread
-}
-
-// In widget's handle_event:
-impl Widget for MyWidget {
-    fn handle_event(&mut self, cx: &mut Cx, event: &Event, scope: &mut Scope) {
-        // Poll for updates on Signal events
-        if let Event::Signal = event {
-            while let Some(update) = PENDING_UPDATES.pop() {
-                match update {
-                    DataUpdate::NewItem { item } => {
-                        self.items.push(item);
-                        self.redraw(cx);
-                    }
-                    // ... handle other updates
-                }
-            }
-        }
-    }
-}
-```
-
-## Startup Sequence
-
-```rust
-impl MatchEvent for App {
-    fn handle_startup(&mut self, cx: &mut Cx) {
-        // 1. Initialize logging
-        let _ = tracing_subscriber::fmt::try_init();
-
-        // 2. Initialize app data directory
-        let _app_data_dir = crate::app_data_dir();
-
-        // 3. Load persisted state
-        if let Err(e) = persistence::load_window_state(
-            self.ui.window(ids!(main_window)), cx
-        ) {
-            error!("Failed to load window state: {}", e);
-        }
-
-        // 4. Update UI based on loaded state
-        self.update_ui_visibility(cx);
-
-        // 5. Start async runtime
-        let _rt_handle = crate::start_async_runtime().unwrap();
-    }
-}
-```
-
-## Shutdown Sequence
-
-```rust
-impl AppMain for App {
-    fn handle_event(&mut self, cx: &mut Cx, event: &Event) {
-        if let Event::Shutdown = event {
-            // Save window geometry
-            let window_ref = self.ui.window(ids!(main_window));
-            if let Err(e) = persistence::save_window_state(window_ref, cx) {
-                error!("Failed to save window state: {e}");
-            }
-
-            // Save app state
-            if let Some(user_id) = current_user_id() {
-                if let Err(e) = persistence::save_app_state(
-                    self.app_state.clone(), user_id
-                ) {
-                    error!("Failed to save app state: {e}");
-                }
-            }
-        }
-        // ... rest of event handling
-    }
-}
-```
-
-## Best Practices
-
-1. **Separation of Concerns**: Keep UI logic on the main thread, async operations in Tokio runtime
-2. **Request/Response Pattern**: Use typed enums for requests and actions
-3. **Lock-Free Updates**: Use `crossbeam::SegQueue` for high-frequency background updates
-4. **SignalToUI**: Always call `SignalToUI::set_ui_signal()` after enqueueing updates
-5. **Cx::post_action()**: Use for async task results that need action handling
-6. **Scope::with_data()**: Pass shared state through widget tree
-7. **Module Registration Order**: Register base widgets before dependent modules in `live_register()`
-
-## Reference Files
-
-- `references/tokio-integration.md` - Detailed Tokio runtime patterns (Robrix)
-- `references/channel-patterns.md` - Channel communication patterns (Robrix)
-- `references/moly-async-patterns.md` - Cross-platform async patterns (Moly)
-  - `PlatformSend` trait for native/WASM compatibility
-  - `UiRunner` for async defer operations
-  - `AbortOnDropHandle` for task cancellation
-  - `ThreadToken` for non-Send types on WASM
-  - `spawn()` platform-agnostic function

package/templates/vault/robius-event-action/SKILL.md

@@ -1,359 +0,0 @@
----
-name: robius-event-action
-description: |
-  CRITICAL: Use for Robius event and action patterns. Triggers on:
-  custom action, MatchEvent, post_action, cx.widget_action,
-  handle_actions, DefaultNone, widget action, event handling,
-  事件处理, 自定义动作
----
-
-# Robius Event and Action Patterns Skill
-
-Best practices for event handling and action patterns in Makepad applications based on Robrix and Moly codebases.
-
-**Source codebases:**
-- **Robrix**: Matrix chat client - MessageAction, RoomsListAction, AppStateAction
-- **Moly**: AI chat application - StoreAction, ChatAction, NavigationAction, Timer patterns
-
-## Triggers
-
-Use this skill when:
-- Implementing custom actions in Makepad
-- Handling events in widgets
-- Centralizing action handling in App
-- Widget-to-widget communication
-- Keywords: makepad action, makepad event, widget action, handle_actions, cx.widget_action
-
-## Custom Action Pattern
-
-### Defining Domain-Specific Actions
-
-```rust
-use makepad_widgets::*;
-
-/// Actions emitted by the Message widget
-#[derive(Clone, DefaultNone, Debug)]
-pub enum MessageAction {
-    /// User wants to react to a message
-    React { details: MessageDetails, reaction: String },
-    /// User wants to reply to a message
-    Reply(MessageDetails),
-    /// User wants to edit a message
-    Edit(MessageDetails),
-    /// User wants to delete a message
-    Delete(MessageDetails),
-    /// User requested to open context menu
-    OpenContextMenu { details: MessageDetails, abs_pos: DVec2 },
-    /// Required default variant
-    None,
-}
-
-/// Data associated with a message action
-#[derive(Clone, Debug)]
-pub struct MessageDetails {
-    pub room_id: OwnedRoomId,
-    pub event_id: OwnedEventId,
-    pub content: String,
-    pub sender_id: OwnedUserId,
-}
-```
-
-### Emitting Actions from Widgets
-
-```rust
-impl Widget for Message {
-    fn handle_event(&mut self, cx: &mut Cx, event: &Event, scope: &mut Scope) {
-        self.view.handle_event(cx, event, scope);
-
-        let area = self.view.area();
-        match event.hits(cx, area) {
-            Hit::FingerDown(_fe) => {
-                cx.set_key_focus(area);
-            }
-            Hit::FingerUp(fe) => {
-                if fe.is_over && fe.is_primary_hit() && fe.was_tap() {
-                    // Emit widget action
-                    cx.widget_action(
-                        self.widget_uid(),
-                        &scope.path,
-                        MessageAction::Reply(self.get_details()),
-                    );
-                }
-            }
-            Hit::FingerLongPress(lpe) => {
-                cx.widget_action(
-                    self.widget_uid(),
-                    &scope.path,
-                    MessageAction::OpenContextMenu {
-                        details: self.get_details(),
-                        abs_pos: lpe.abs,
-                    },
-                );
-            }
-            _ => {}
-        }
-    }
-}
-```
-
-## Centralized Action Handling in App
-
-### Using MatchEvent Trait
-
-```rust
-impl MatchEvent for App {
-    fn handle_startup(&mut self, cx: &mut Cx) {
-        // Called once on app startup
-        self.initialize(cx);
-    }
-
-    fn handle_actions(&mut self, cx: &mut Cx, actions: &Actions) {
-        for action in actions {
-            // Pattern 1: Direct downcast for non-widget actions
-            if let Some(action) = action.downcast_ref::<LoginAction>() {
-                match action {
-                    LoginAction::LoginSuccess => {
-                        self.app_state.logged_in = true;
-                        self.update_ui_visibility(cx);
-                    }
-                    LoginAction::LoginFailure(error) => {
-                        self.show_error(cx, error);
-                    }
-                }
-                continue;  // Action handled
-            }
-
-            // Pattern 2: Widget action cast
-            if let MessageAction::OpenContextMenu { details, abs_pos } =
-                action.as_widget_action().cast()
-            {
-                self.show_context_menu(cx, details, abs_pos);
-                continue;
-            }
-
-            // Pattern 3: Match on downcast_ref for enum variants
-            match action.downcast_ref() {
-                Some(AppStateAction::RoomFocused(room)) => {
-                    self.app_state.selected_room = Some(room.clone());
-                    continue;
-                }
-                Some(AppStateAction::NavigateToRoom { destination }) => {
-                    self.navigate_to_room(cx, destination);
-                    continue;
-                }
-                _ => {}
-            }
-
-            // Pattern 4: Modal actions
-            match action.downcast_ref() {
-                Some(ModalAction::Open { kind }) => {
-                    self.ui.modal(ids!(my_modal)).open(cx);
-                    continue;
-                }
-                Some(ModalAction::Close { was_internal }) => {
-                    if *was_internal {
-                        self.ui.modal(ids!(my_modal)).close(cx);
-                    }
-                    continue;
-                }
-                _ => {}
-            }
-        }
-    }
-}
-
-impl AppMain for App {
-    fn handle_event(&mut self, cx: &mut Cx, event: &Event) {
-        // Forward to MatchEvent
-        self.match_event(cx, event);
-
-        // Pass events to widget tree
-        let scope = &mut Scope::with_data(&mut self.app_state);
-        self.ui.handle_event(cx, event, scope);
-    }
-}
-```
-
-## Action Types
-
-### Widget Actions (UI Thread)
-
-Emitted by widgets, handled in the same frame:
-
-```rust
-// Emitting
-cx.widget_action(
-    self.widget_uid(),
-    &scope.path,
-    MyAction::Something,
-);
-
-// Handling (two patterns)
-// Pattern A: Direct cast for widget actions
-if let MyAction::Something = action.as_widget_action().cast() {
-    // handle...
-}
-
-// Pattern B: With widget UID matching
-if let Some(uid) = action.as_widget_action().widget_uid() {
-    if uid == my_expected_uid {
-        if let MyAction::Something = action.as_widget_action().cast() {
-            // handle...
-        }
-    }
-}
-```
-
-### Posted Actions (From Async)
-
-Posted from async tasks, received in next event cycle:
-
-```rust
-// In async task
-Cx::post_action(DataFetchedAction { data });
-SignalToUI::set_ui_signal();  // Wake UI thread
-
-// Handling in App (NOT widget actions)
-if let Some(action) = action.downcast_ref::<DataFetchedAction>() {
-    self.process_data(&action.data);
-}
-```
-
-### Global Actions
-
-For app-wide state changes:
-
-```rust
-// Using cx.action() for global actions
-cx.action(NavigationAction::GoBack);
-
-// Handling
-if let Some(NavigationAction::GoBack) = action.downcast_ref() {
-    self.navigate_back(cx);
-}
-```
-
-## Event Handling Patterns
-
-### Hit Testing
-
-```rust
-impl Widget for MyWidget {
-    fn handle_event(&mut self, cx: &mut Cx, event: &Event, scope: &mut Scope) {
-        let area = self.view.area();
-        match event.hits(cx, area) {
-            Hit::FingerDown(fe) => {
-                cx.set_key_focus(area);
-                // Start drag, capture, etc.
-            }
-            Hit::FingerUp(fe) => {
-                if fe.is_over && fe.is_primary_hit() {
-                    if fe.was_tap() {
-                        // Single tap
-                    }
-                    if fe.was_long_press() {
-                        // Long press
-                    }
-                }
-            }
-            Hit::FingerMove(fe) => {
-                // Drag handling
-            }
-            Hit::FingerHoverIn(_) => {
-                self.animator_play(cx, id!(hover.on));
-            }
-            Hit::FingerHoverOut(_) => {
-                self.animator_play(cx, id!(hover.off));
-            }
-            Hit::FingerScroll(se) => {
-                // Scroll handling
-            }
-            _ => {}
-        }
-    }
-}
-```
-
-### Keyboard Events
-
-```rust
-fn handle_event(&mut self, cx: &mut Cx, event: &Event, scope: &mut Scope) {
-    if let Event::KeyDown(ke) = event {
-        match ke.key_code {
-            KeyCode::Return if !ke.modifiers.shift => {
-                self.submit(cx);
-            }
-            KeyCode::Escape => {
-                self.cancel(cx);
-            }
-            KeyCode::KeyC if ke.modifiers.control || ke.modifiers.logo => {
-                self.copy_to_clipboard(cx);
-            }
-            _ => {}
-        }
-    }
-}
-```
-
-### Signal Events
-
-For handling async updates:
-
-```rust
-fn handle_event(&mut self, cx: &mut Cx, event: &Event, scope: &mut Scope) {
-    if let Event::Signal = event {
-        // Poll update queues
-        while let Some(update) = PENDING_UPDATES.pop() {
-            self.apply_update(cx, update);
-        }
-    }
-}
-```
-
-## Action Chaining Pattern
-
-Widget emits action → Parent catches and re-emits with more context:
-
-```rust
-// In child widget
-cx.widget_action(
-    self.widget_uid(),
-    &scope.path,
-    ItemAction::Selected(item_id),
-);
-
-// In parent widget's handle_event
-if let ItemAction::Selected(item_id) = action.as_widget_action().cast() {
-    // Add context and forward to App
-    cx.widget_action(
-        self.widget_uid(),
-        &scope.path,
-        ListAction::ItemSelected {
-            list_id: self.list_id.clone(),
-            item_id,
-        },
-    );
-}
-```
-
-## Best Practices
-
-1. **Use `DefaultNone` derive**: All action enums must have a `None` variant
-2. **Use `continue` after handling**: Prevents unnecessary processing
-3. **Downcast pattern for async actions**: Posted actions are not widget actions
-4. **Widget action cast for UI actions**: Use `as_widget_action().cast()`
-5. **Always call `SignalToUI::set_ui_signal()`**: After posting actions from async
-6. **Centralize in App::handle_actions**: Keep action handling in one place
-7. **Use descriptive action names**: `MessageAction::Reply` not `MessageAction::Action1`
-
-## Reference Files
-
-- `references/action-patterns.md` - Additional action patterns (Robrix)
-- `references/event-handling.md` - Event handling reference (Robrix)
-- `references/moly-action-patterns.md` - Moly-specific patterns
-  - Store-based action forwarding
-  - Timer-based retry pattern
-  - Radio button navigation
-  - External link handling
-  - Platform-conditional actions (#[cfg])
-  - UiRunner event handling