claude-mpm 4.20.3__py3-none-any.whl → 4.25.10__py3-none-any.whl

claude_mpm/d2/SVELTE5_STORES_GUIDE.md

@@ -0,0 +1,180 @@
+# Svelte 5 Store Architecture Guide
+
+## Quick Decision Tree
+
+```
+Do you need reactive state?
+│
+├─ YES → Is it used inside a component <script> block?
+│        │
+│        ├─ YES → Use Svelte 5 Runes ✅
+│        │        let count = $state(0)
+│        │        let doubled = $derived(count * 2)
+│        │
+│        └─ NO → Is it at module level / shared between components?
+│                 │
+│                 └─ YES → Use Traditional Stores ✅
+│                          const count = writable(0)
+│                          const doubled = derived(count, $count => $count * 2)
+│
+└─ NO → Use regular JavaScript variables
+```
+
+## Pattern 1: Component-Local State (Use Runes)
+
+```svelte
+<!-- Component.svelte -->
+<script>
+  // ✅ CORRECT - Runes in component context
+  let count = $state(0);
+  let doubled = $derived(count * 2);
+
+  $effect(() => {
+    console.log(`Count is now ${count}`);
+  });
+</script>
+
+<button onclick={() => count++}>
+  {count} / {doubled}
+</button>
+```
+
+## Pattern 2: Module-Level Stores (Use Traditional Stores)
+
+```javascript
+// stores/counter.js
+import { writable, derived } from 'svelte/store';
+
+// ✅ CORRECT - Traditional stores for module-level state
+function createCounterStore() {
+  const count = writable(0);
+  const doubled = derived(count, $count => $count * 2);
+
+  return {
+    count: { subscribe: count.subscribe },
+    doubled: { subscribe: doubled.subscribe },
+    increment: () => count.update(n => n + 1),
+    reset: () => count.set(0)
+  };
+}
+
+export const counterStore = createCounterStore();
+```
+
+```svelte
+<!-- Component.svelte -->
+<script>
+  import { counterStore } from './stores/counter.js';
+
+  // Use $ auto-subscription
+</script>
+
+<button onclick={() => counterStore.increment()}>
+  {$counterStore.count} / {$counterStore.doubled}
+</button>
+```
+
+## Pattern 3: Props (Use $props)
+
+```svelte
+<!-- Child.svelte -->
+<script>
+  // ✅ CORRECT - $props for component props
+  let { value, onUpdate } = $props();
+</script>
+
+<input bind:value oninput={() => onUpdate(value)} />
+```
+
+## Common Mistakes
+
+### ❌ WRONG: Runes at Module Level
+
+```javascript
+// stores/counter.svelte.js
+// ❌ This will cause effect_orphan error!
+function createCounterStore() {
+  let count = $state(0);  // ❌ Rune outside component
+  // ...
+}
+
+export const counterStore = createCounterStore(); // ❌ Called at module load
+```
+
+### ❌ WRONG: Traditional Stores in Components
+
+```svelte
+<script>
+  import { writable } from 'svelte/store';
+
+  // ❌ Unnecessary complexity for component-local state
+  const count = writable(0);
+</script>
+
+<button onclick={() => count.update(n => n + 1)}>
+  {$count}
+</button>
+```
+
+### ✅ CORRECT: Runes in Components
+
+```svelte
+<script>
+  // ✅ Simple and idiomatic
+  let count = $state(0);
+</script>
+
+<button onclick={() => count++}>
+  {count}
+</button>
+```
+
+## Migration Checklist
+
+When converting Svelte 4 → Svelte 5:
+
+### Component-Local State
+- [ ] `export let prop` → `let { prop } = $props()`
+- [ ] `$: derived = compute(x)` → `let derived = $derived(compute(x))`
+- [ ] `$: { effect() }` → `$effect(() => { effect() })`
+
+### Module-Level Stores
+- [ ] Keep using `writable`, `derived`, `readable`
+- [ ] Update components to use `$` auto-subscription
+- [ ] Add `.subscribe` exposure in store API
+
+### File Naming
+- [ ] Component stores using runes: `Component.svelte` (not `.svelte.js`)
+- [ ] Module stores: `store.js` (not `.svelte.js`)
+
+## Debugging Tips
+
+### Error: `effect_orphan`
+**Cause**: Runes used outside component context
+**Fix**: Use traditional stores for module-level state
+
+### Error: Cannot access `$store` before initialization
+**Cause**: Missing `$` prefix on store subscription
+**Fix**: Use `$storeName.property` in templates
+
+### Store not updating UI
+**Cause**: Forgetting to use `.set()` or `.update()`
+**Fix**: Always mutate stores with `.set()` / `.update()`, never directly
+
+## Performance Comparison
+
+| Pattern | Bundle Impact | Reactivity | Use Case |
+|---------|---------------|------------|----------|
+| Runes | Minimal | Fine-grained | Component-local |
+| Traditional Stores | Small | Observable | Shared state |
+| Context API | None | Manual | Dependency injection |
+
+## Further Reading
+
+- Svelte 5 Runes: https://svelte.dev/docs/svelte/$state
+- Svelte Stores: https://svelte.dev/docs/svelte-store
+- Migration Guide: https://svelte-5-preview.vercel.app/docs/v5-migration-guide
+
+---
+
+**Remember**: Runes are for components, stores are for modules.

claude_mpm/d2/TESTING.md

@@ -0,0 +1,288 @@
+# Testing Checklist for Dashboard2
+
+## Build Verification
+
+- [x] `npm install` completes without errors
+- [x] `npm run build` completes successfully
+- [x] No Svelte compiler warnings
+- [x] No accessibility warnings
+- [x] `dist/index.html` exists
+- [x] `dist/assets/*.js` exists
+- [x] `dist/assets/*.css` exists
+
+## Development Server Testing
+
+Run `npm run dev` and verify:
+
+- [ ] Dev server starts on port 5173
+- [ ] Dashboard loads at `http://localhost:5173`
+- [ ] No console errors on page load
+- [ ] Hot Module Replacement (HMR) works on file changes
+
+## UI Components
+
+### Header
+- [ ] Title displays: "Claude MPM Dashboard"
+- [ ] Version displays: "v2.0"
+- [ ] Connection status indicator is visible
+- [ ] Status text shows "Disconnected" initially
+- [ ] Port number displays correctly
+- [ ] Indicator color is red when disconnected
+
+### Sidebar
+- [ ] All 5 tabs are visible: Events, Agents, Files, Tools, Activity
+- [ ] Each tab has an icon
+- [ ] Events tab is active by default
+- [ ] Clicking tabs switches active state
+- [ ] Active tab has blue highlight
+- [ ] Hover effects work correctly
+
+### Main Content
+- [ ] Events tab content loads
+- [ ] Other tabs show placeholder content
+- [ ] Placeholder icons display correctly
+- [ ] Content area fills remaining space
+
+## Socket.IO Connection
+
+### Local Connection (port 8765)
+- [ ] Connection status changes to "Connecting..." on startup
+- [ ] Status changes to "Connected" when server is available
+- [ ] Indicator turns green on connection
+- [ ] Port number matches server (8765)
+- [ ] Status shows "Disconnected" when server unavailable
+- [ ] Status shows "Reconnecting..." when connection lost
+- [ ] Indicator turns yellow during reconnection
+- [ ] Auto-reconnect works after temporary disconnection
+
+### Console Logging
+Check browser console for:
+- [ ] Socket.IO connection events logged
+- [ ] No connection errors (if server running)
+- [ ] Event reception logged
+- [ ] No JavaScript errors
+
+## Events Tab Functionality
+
+### Empty State
+- [ ] Empty state displays when no events
+- [ ] "Waiting for events..." message shown
+- [ ] Hint text displays
+- [ ] Icon (📡) is visible
+
+### Event Display
+- [ ] Events appear when received
+- [ ] Events display in reverse chronological order (newest first)
+- [ ] Event time is formatted correctly (HH:MM:SS.mmm)
+- [ ] Event source badge displays with correct color:
+  - Hook: Blue (#3b82f6)
+  - System: Green (#10b981)
+  - API: Orange (#f59e0b)
+- [ ] Event summary shows type and subtype
+- [ ] Event item is clickable
+
+### Event Expansion
+- [ ] Clicking event expands JSON details
+- [ ] Expand icon changes from ▶ to ▼
+- [ ] JSON is formatted with syntax highlighting
+- [ ] JSON is scrollable horizontally if needed
+- [ ] Clicking again collapses the event
+- [ ] Only one event expanded at a time (optional behavior)
+
+### Event Statistics
+- [ ] "Total" counter increments with each event
+- [ ] "Displayed" counter shows current count
+- [ ] Numbers update in real-time
+- [ ] Clear button appears when events exist
+- [ ] Clear button removes all events
+- [ ] Counters reset after clearing
+
+### Auto-scroll
+- [ ] New events auto-scroll to top
+- [ ] User can scroll manually
+- [ ] Auto-scroll doesn't interfere with manual scrolling
+
+## Event Reception Testing
+
+### Test with Mock Events
+
+You can test event reception by running this in the browser console:
+
+```javascript
+// Simulate a claude_event
+window.dispatchEvent(new CustomEvent('test-socket-event', {
+  detail: {
+    source: 'hook',
+    type: 'tool',
+    subtype: 'pre_tool',
+    timestamp: new Date().toISOString(),
+    data: {
+      tool_name: 'test_tool',
+      params: { test: true }
+    }
+  }
+}));
+```
+
+Or emit directly via Socket.IO if connected:
+```javascript
+// Get socket from console
+const socket = io('http://localhost:8765');
+socket.emit('claude_event', {
+  source: 'hook',
+  type: 'test',
+  subtype: 'console_test',
+  timestamp: new Date().toISOString(),
+  data: { message: 'Test from console' }
+});
+```
+
+### Real Event Testing
+- [ ] Trigger a Claude Code hook event
+- [ ] Event appears in dashboard immediately
+- [ ] Event data is complete and accurate
+- [ ] Timestamp is correct
+- [ ] Event can be expanded to view full JSON
+- [ ] Multiple events display correctly
+- [ ] High-frequency events don't cause UI lag
+
+### Heartbeat Events
+- [ ] Server heartbeat events appear (every 3 minutes)
+- [ ] Heartbeat has "system" source
+- [ ] Heartbeat data includes uptime
+- [ ] Heartbeat data includes connected clients
+
+## Performance Testing
+
+### Large Event Loads
+- [ ] Dashboard handles 100 events smoothly
+- [ ] Dashboard handles 1000 events (max buffer)
+- [ ] Events beyond 1000 are trimmed correctly
+- [ ] No memory leaks with continuous events
+- [ ] Scrolling remains smooth with full buffer
+
+### Network
+- [ ] Dashboard works on slow connections
+- [ ] Reconnection works after network interruption
+- [ ] Events buffer during disconnection (if implemented)
+- [ ] No duplicate events after reconnection
+
+## Cross-Browser Testing
+
+- [ ] Chrome/Chromium (latest)
+- [ ] Firefox (latest)
+- [ ] Safari (latest)
+- [ ] Edge (latest)
+
+Check for:
+- [ ] Layout renders correctly
+- [ ] WebSocket/Socket.IO works
+- [ ] No console errors
+- [ ] Animations work smoothly
+
+## Accessibility Testing
+
+- [ ] Keyboard navigation works
+- [ ] Tab key moves through interactive elements
+- [ ] Enter/Space activates buttons
+- [ ] Screen reader can read content
+- [ ] Color contrast meets WCAG standards
+- [ ] Focus indicators are visible
+
+## Responsive Design
+
+Test at different viewport sizes:
+- [ ] 1920x1080 (Full HD)
+- [ ] 1366x768 (Laptop)
+- [ ] 1024x768 (Tablet landscape)
+
+Verify:
+- [ ] Layout doesn't break
+- [ ] All content is accessible
+- [ ] No horizontal scrolling
+- [ ] Sidebar width is appropriate
+
+## Production Build Testing
+
+After running `npm run build`:
+
+1. **Static File Serving**:
+   - [ ] Serve dist/ with a simple HTTP server
+   - [ ] Dashboard loads correctly
+   - [ ] Assets load from correct paths
+   - [ ] No 404 errors for assets
+
+2. **Integration Testing**:
+   - [ ] Flask serves dashboard correctly
+   - [ ] Base path `/dashboard2/` works
+   - [ ] Assets load with correct paths
+   - [ ] Socket.IO connects to correct port
+
+3. **Size Optimization**:
+   - [ ] Total bundle size < 100KB (gzipped)
+   - [ ] Initial load time < 2 seconds
+   - [ ] No unnecessary dependencies bundled
+
+## Error Handling
+
+Test error scenarios:
+- [ ] Server not available: Shows "Disconnected" status
+- [ ] Server crashes: Shows reconnection status
+- [ ] Invalid event data: Handles gracefully (no crashes)
+- [ ] Malformed JSON: Displays error or skips event
+- [ ] Network timeout: Retries connection
+
+## Console Checks
+
+Verify no errors for:
+- [ ] Component initialization
+- [ ] Socket.IO connection
+- [ ] Event handling
+- [ ] State updates
+- [ ] DOM updates
+
+## Final Production Checklist
+
+Before deploying:
+- [ ] Run `npm run build` with no warnings
+- [ ] Test built files locally
+- [ ] Verify all features work in production build
+- [ ] Check browser console for errors
+- [ ] Test Socket.IO connection
+- [ ] Verify events display correctly
+- [ ] Test on target deployment environment
+- [ ] Document any known issues
+- [ ] Update version number if needed
+
+## Known Issues
+
+Document any issues found during testing:
+
+1. **Issue**: [Description]
+   - **Severity**: Low/Medium/High
+   - **Workaround**: [If available]
+   - **Fix plan**: [If scheduled]
+
+## Performance Benchmarks
+
+Record baseline performance:
+- Initial load time: ___ms
+- Time to Socket.IO connection: ___ms
+- Average event processing time: ___ms
+- Memory usage with 1000 events: ___MB
+- FPS during scrolling: ___
+
+## Test Results Summary
+
+Date: ___________
+Tester: ___________
+Environment: ___________
+
+- Total tests: ___
+- Passed: ___
+- Failed: ___
+- Skipped: ___
+
+**Overall Status**: ⬜ Pass | ⬜ Fail | ⬜ Partial
+
+**Notes**:

claude_mpm/d2/index.html

@@ -0,0 +1,118 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Claude MPM Dashboard</title>
+  <style>
+    * {
+      margin: 0;
+      padding: 0;
+      box-sizing: border-box;
+    }
+
+    /* CSS Custom Properties for Theming */
+    :root {
+      /* Light mode (default) */
+      --bg-primary: #ffffff;
+      --bg-secondary: #f5f5f5;
+      --bg-tertiary: #e8e8e8;
+      --bg-elevated: #ffffff;
+      --text-primary: #1a1a1a;
+      --text-secondary: #666666;
+      --text-tertiary: #888888;
+      --border-color: #e0e0e0;
+      --border-color-light: #f0f0f0;
+      --accent-color: #3b82f6;
+      --accent-hover: #2563eb;
+      --success-color: #10b981;
+      --error-color: #ef4444;
+      --warning-color: #f59e0b;
+      --header-bg-start: #f8f9fa;
+      --header-bg-end: #e9ecef;
+      --sidebar-bg: #fafafa;
+      --card-bg: #ffffff;
+      --shadow-sm: 0 1px 3px rgba(0, 0, 0, 0.1);
+      --shadow-md: 0 2px 8px rgba(0, 0, 0, 0.1);
+      --shadow-lg: 0 4px 16px rgba(0, 0, 0, 0.1);
+      --overlay-bg: rgba(0, 0, 0, 0.05);
+      --overlay-border: rgba(0, 0, 0, 0.1);
+      --input-bg: #ffffff;
+      --input-border: #d1d5db;
+      --tab-hover-bg: rgba(0, 0, 0, 0.05);
+      --scrollbar-track: #f1f1f1;
+      --scrollbar-thumb: #c1c1c1;
+      --scrollbar-thumb-hover: #a8a8a8;
+    }
+
+    [data-theme="dark"] {
+      /* Dark mode */
+      --bg-primary: #0f0f0f;
+      --bg-secondary: #1a1a1a;
+      --bg-tertiary: #2d2d2d;
+      --bg-elevated: #1a1a1a;
+      --text-primary: #ffffff;
+      --text-secondary: #a0a0a0;
+      --text-tertiary: #888888;
+      --border-color: #333333;
+      --border-color-light: #404040;
+      --accent-color: #60a5fa;
+      --accent-hover: #3b82f6;
+      --success-color: #34d399;
+      --error-color: #f87171;
+      --warning-color: #fbbf24;
+      --header-bg-start: #1a1a1a;
+      --header-bg-end: #2d2d2d;
+      --sidebar-bg: #141414;
+      --card-bg: #1a1a1a;
+      --shadow-sm: 0 1px 3px rgba(0, 0, 0, 0.3);
+      --shadow-md: 0 2px 8px rgba(0, 0, 0, 0.4);
+      --shadow-lg: 0 4px 16px rgba(0, 0, 0, 0.5);
+      --overlay-bg: rgba(255, 255, 255, 0.05);
+      --overlay-border: rgba(255, 255, 255, 0.1);
+      --input-bg: #2d2d2d;
+      --input-border: #404040;
+      --tab-hover-bg: rgba(255, 255, 255, 0.05);
+      --scrollbar-track: #1a1a1a;
+      --scrollbar-thumb: #404040;
+      --scrollbar-thumb-hover: #505050;
+    }
+
+    body {
+      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen, Ubuntu, Cantarell, sans-serif;
+      background: var(--bg-primary);
+      color: var(--text-primary);
+      overflow: hidden;
+      transition: background-color 0.3s ease, color 0.3s ease;
+    }
+
+    /* Smooth transitions for theme changes */
+    * {
+      transition: background-color 0.3s ease, color 0.3s ease, border-color 0.3s ease;
+    }
+
+    /* Custom scrollbar theming */
+    ::-webkit-scrollbar {
+      width: 8px;
+      height: 8px;
+    }
+
+    ::-webkit-scrollbar-track {
+      background: var(--scrollbar-track);
+    }
+
+    ::-webkit-scrollbar-thumb {
+      background: var(--scrollbar-thumb);
+      border-radius: 4px;
+    }
+
+    ::-webkit-scrollbar-thumb:hover {
+      background: var(--scrollbar-thumb-hover);
+    }
+  </style>
+</head>
+<body>
+  <div id="app"></div>
+  <script type="module" src="/src/main.js"></script>
+</body>
+</html>

claude_mpm/d2/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "claude-mpm-d2",
+  "version": "1.0.0",
+  "description": "Svelte 5-based dashboard for Claude MPM",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "preview": "vite preview"
+  },
+  "devDependencies": {
+    "@sveltejs/vite-plugin-svelte": "^4.0.0",
+    "svelte": "^5.0.0",
+    "vite": "^5.0.0"
+  },
+  "dependencies": {
+    "socket.io-client": "^4.7.5"
+  }
+}

claude_mpm/d2/src/App.svelte

@@ -0,0 +1,110 @@
+<script>
+  import { onMount, onDestroy } from 'svelte';
+  import Header from './components/Header.svelte';
+  import Sidebar from './components/Sidebar.svelte';
+  import MainContent from './components/MainContent.svelte';
+  import { socketStore } from './stores/socket.js';
+  import { eventsStore } from './stores/events.js';
+  import { themeStore } from './stores/theme.js';
+
+  // Destructure individual stores from socketStore
+  const { statusText, statusColor, port } = socketStore;
+
+  let activeTab = $state('events');
+
+  // Socket.IO client instance (set during onMount)
+  let client = null;
+
+  // Event handler functions (defined outside lifecycle for proper cleanup)
+  function handleClaudeEvent(data) {
+    console.log('Received claude_event:', data);
+    eventsStore.addEvent(data);
+  }
+
+  function handleHeartbeat(data) {
+    console.log('Received heartbeat:', data);
+    eventsStore.addEvent({
+      source: 'system',
+      type: 'heartbeat',
+      timestamp: data.timestamp,
+      data: data
+    });
+  }
+
+  function handleAnyEvent(eventName, ...args) {
+    if (eventName !== 'claude_event' && eventName !== 'heartbeat' && eventName !== 'connection_status') {
+      console.log('Received event:', eventName, args);
+    }
+  }
+
+  onMount(() => {
+    // Initialize theme on mount
+    themeStore.initialize();
+
+    // Connect to Socket.IO server
+    socketStore.connect();
+
+    // Get the client and listen for events
+    client = socketStore.getClient();
+    if (client) {
+      // Listen for Claude Code events
+      client.on('claude_event', handleClaudeEvent);
+
+      // Listen for heartbeat events
+      client.on('heartbeat', handleHeartbeat);
+
+      // Listen for any other events (for debugging)
+      client.socket.onAny(handleAnyEvent);
+    }
+  });
+
+  onDestroy(() => {
+    // Cleanup event listeners before disconnect
+    if (client) {
+      client.off('claude_event', handleClaudeEvent);
+      client.off('heartbeat', handleHeartbeat);
+      if (client.socket) {
+        client.socket.offAny(handleAnyEvent);
+      }
+    }
+
+    // Disconnect Socket.IO
+    socketStore.disconnect();
+  });
+</script>
+
+<div class="app">
+  <Header
+    statusText={$statusText}
+    statusColor={$statusColor}
+    port={$port}
+  />
+
+  <div class="app-body">
+    <Sidebar bind:activeTab={activeTab} />
+    <MainContent activeTab={activeTab} />
+  </div>
+</div>
+
+<style>
+  :global(body) {
+    margin: 0;
+    padding: 0;
+    overflow: hidden;
+  }
+
+  .app {
+    width: 100vw;
+    height: 100vh;
+    display: flex;
+    flex-direction: column;
+    background: var(--bg-primary);
+    color: var(--text-primary);
+  }
+
+  .app-body {
+    flex: 1;
+    display: flex;
+    overflow: hidden;
+  }
+</style>