codehava-agent-kit 1.0.1 → 2.0.0

package/templates/.agent/skills/react-ui-patterns/SKILL.md

@@ -0,0 +1,295 @@
+---
+name: react-ui-patterns
+description: "Modern React UI patterns for loading states, error handling, and data fetching. Use when building UI components, handling async data, or managing UI states."
+risk: unknown
+source: community
+date_added: "2026-02-27"
+---
+
+# React UI Patterns
+
+## Core Principles
+
+1. **Never show stale UI** - Loading spinners only when actually loading
+2. **Always surface errors** - Users must know when something fails
+3. **Optimistic updates** - Make the UI feel instant
+4. **Progressive disclosure** - Show content as it becomes available
+5. **Graceful degradation** - Partial data is better than no data
+
+## Loading State Patterns
+
+### The Golden Rule
+
+**Show loading indicator ONLY when there's no data to display.**
+
+```typescript
+// CORRECT - Only show loading when no data exists
+const { data, loading, error } = useGetItemsQuery();
+
+if (error) return <ErrorState error={error} onRetry={refetch} />;
+if (loading && !data) return <LoadingState />;
+if (!data?.items.length) return <EmptyState />;
+
+return <ItemList items={data.items} />;
+```
+
+```typescript
+// WRONG - Shows spinner even when we have cached data
+if (loading) return <LoadingState />; // Flashes on refetch!
+```
+
+### Loading State Decision Tree
+
+```
+Is there an error?
+  → Yes: Show error state with retry option
+  → No: Continue
+
+Is it loading AND we have no data?
+  → Yes: Show loading indicator (spinner/skeleton)
+  → No: Continue
+
+Do we have data?
+  → Yes, with items: Show the data
+  → Yes, but empty: Show empty state
+  → No: Show loading (fallback)
+```
+
+### Skeleton vs Spinner
+
+| Use Skeleton When | Use Spinner When |
+|-------------------|------------------|
+| Known content shape | Unknown content shape |
+| List/card layouts | Modal actions |
+| Initial page load | Button submissions |
+| Content placeholders | Inline operations |
+
+## Error Handling Patterns
+
+### The Error Handling Hierarchy
+
+```
+1. Inline error (field-level) → Form validation errors
+2. Toast notification → Recoverable errors, user can retry
+3. Error banner → Page-level errors, data still partially usable
+4. Full error screen → Unrecoverable, needs user action
+```
+
+### Always Show Errors
+
+**CRITICAL: Never swallow errors silently.**
+
+```typescript
+// CORRECT - Error always surfaced to user
+const [createItem, { loading }] = useCreateItemMutation({
+  onCompleted: () => {
+    toast.success({ title: 'Item created' });
+  },
+  onError: (error) => {
+    console.error('createItem failed:', error);
+    toast.error({ title: 'Failed to create item' });
+  },
+});
+
+// WRONG - Error silently caught, user has no idea
+const [createItem] = useCreateItemMutation({
+  onError: (error) => {
+    console.error(error); // User sees nothing!
+  },
+});
+```
+
+### Error State Component Pattern
+
+```typescript
+interface ErrorStateProps {
+  error: Error;
+  onRetry?: () => void;
+  title?: string;
+}
+
+const ErrorState = ({ error, onRetry, title }: ErrorStateProps) => (
+  <div className="error-state">
+    <Icon name="exclamation-circle" />
+    <h3>{title ?? 'Something went wrong'}</h3>
+    <p>{error.message}</p>
+    {onRetry && (
+      <Button onClick={onRetry}>Try Again</Button>
+    )}
+  </div>
+);
+```
+
+## Button State Patterns
+
+### Button Loading State
+
+```tsx
+<Button
+  onClick={handleSubmit}
+  isLoading={isSubmitting}
+  disabled={!isValid || isSubmitting}
+>
+  Submit
+</Button>
+```
+
+### Disable During Operations
+
+**CRITICAL: Always disable triggers during async operations.**
+
+```tsx
+// CORRECT - Button disabled while loading
+<Button
+  disabled={isSubmitting}
+  isLoading={isSubmitting}
+  onClick={handleSubmit}
+>
+  Submit
+</Button>
+
+// WRONG - User can tap multiple times
+<Button onClick={handleSubmit}>
+  {isSubmitting ? 'Submitting...' : 'Submit'}
+</Button>
+```
+
+## Empty States
+
+### Empty State Requirements
+
+Every list/collection MUST have an empty state:
+
+```tsx
+// WRONG - No empty state
+return <FlatList data={items} />;
+
+// CORRECT - Explicit empty state
+return (
+  <FlatList
+    data={items}
+    ListEmptyComponent={<EmptyState />}
+  />
+);
+```
+
+### Contextual Empty States
+
+```tsx
+// Search with no results
+<EmptyState
+  icon="search"
+  title="No results found"
+  description="Try different search terms"
+/>
+
+// List with no items yet
+<EmptyState
+  icon="plus-circle"
+  title="No items yet"
+  description="Create your first item"
+  action={{ label: 'Create Item', onClick: handleCreate }}
+/>
+```
+
+## Form Submission Pattern
+
+```tsx
+const MyForm = () => {
+  const [submit, { loading }] = useSubmitMutation({
+    onCompleted: handleSuccess,
+    onError: handleError,
+  });
+
+  const handleSubmit = async () => {
+    if (!isValid) {
+      toast.error({ title: 'Please fix errors' });
+      return;
+    }
+    await submit({ variables: { input: values } });
+  };
+
+  return (
+    <form>
+      <Input
+        value={values.name}
+        onChange={handleChange('name')}
+        error={touched.name ? errors.name : undefined}
+      />
+      <Button
+        type="submit"
+        onClick={handleSubmit}
+        disabled={!isValid || loading}
+        isLoading={loading}
+      >
+        Submit
+      </Button>
+    </form>
+  );
+};
+```
+
+## Anti-Patterns
+
+### Loading States
+
+```typescript
+// WRONG - Spinner when data exists (causes flash)
+if (loading) return <Spinner />;
+
+// CORRECT - Only show loading without data
+if (loading && !data) return <Spinner />;
+```
+
+### Error Handling
+
+```typescript
+// WRONG - Error swallowed
+try {
+  await mutation();
+} catch (e) {
+  console.log(e); // User has no idea!
+}
+
+// CORRECT - Error surfaced
+onError: (error) => {
+  console.error('operation failed:', error);
+  toast.error({ title: 'Operation failed' });
+}
+```
+
+### Button States
+
+```typescript
+// WRONG - Button not disabled during submission
+<Button onClick={submit}>Submit</Button>
+
+// CORRECT - Disabled and shows loading
+<Button onClick={submit} disabled={loading} isLoading={loading}>
+  Submit
+</Button>
+```
+
+## Checklist
+
+Before completing any UI component:
+
+**UI States:**
+- [ ] Error state handled and shown to user
+- [ ] Loading state shown only when no data exists
+- [ ] Empty state provided for collections
+- [ ] Buttons disabled during async operations
+- [ ] Buttons show loading indicator when appropriate
+
+**Data & Mutations:**
+- [ ] Mutations have onError handler
+- [ ] All user actions have feedback (toast/visual)
+
+## Integration with Other Skills
+
+- **graphql-schema**: Use mutation patterns with proper error handling
+- **testing-patterns**: Test all UI states (loading, error, empty, success)
+- **formik-patterns**: Apply form submission patterns
+
+## When to Use
+This skill is applicable to execute the workflow or actions described in the overview.

package/templates/.agent/skills/robius-app-architecture/SKILL.md

@@ -0,0 +1,330 @@
+---
+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
+risk: unknown
+source: community
+---
+
+# 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