@thierrynakoa/fire-flow 12.2.2 → 13.0.1

package/skills-library/_general/frontend/framer-motion-layoutid-grouping.md

@@ -0,0 +1,150 @@
+---
+name: framer-motion-layoutid-grouping
+category: frontend
+version: 1.0.0
+contributed: 2026-02-26
+contributor: scribe-bible
+last_updated: 2026-02-26
+tags: [framer-motion, animation, FLIP, layout, grouping, sorting, react]
+difficulty: medium
+usage_count: 0
+success_rate: 100
+---
+
+# Framer Motion layoutId Bubble Grouping
+
+## Problem
+
+You have a collection of items (cards, bubbles, tiles) that can be sorted/grouped by different criteria. When the user switches sort mode, items should smoothly animate to their new positions in the new groups — not just re-render instantly. Traditional approaches require manually calculating FLIP (First, Last, Invert, Play) coordinates. CSS Grid/Flexbox reflows don't animate.
+
+## Solution Pattern
+
+Use Framer Motion's `layoutId` prop on `motion.div` or `motion.button` elements. When items move between groups (different parent containers), Framer Motion automatically calculates the FLIP animation — measuring the element's position before and after the React re-render, then animating the transform.
+
+The key: each item needs a **stable, unique `layoutId`** that persists across re-renders. When React re-renders with new grouping, Framer Motion finds the same `layoutId` in a different position and animates the transition.
+
+## Code Example
+
+```tsx
+import { motion, AnimatePresence } from 'framer-motion';
+
+interface Item {
+  id: string;
+  name: string;
+  category: string;
+  author: string;
+  size: number;
+}
+
+type SortMode = 'category' | 'author' | 'size';
+
+function GroupedBubbles({ items }: { items: Item[] }) {
+  const [sortMode, setSortMode] = useState<SortMode>('category');
+
+  // Regroup items whenever sort mode changes
+  const groups = useMemo(() => {
+    const map = new Map<string, Item[]>();
+    items.forEach(item => {
+      const key = sortMode === 'size'
+        ? (item.size > 100 ? 'Large' : 'Small')
+        : item[sortMode];
+      if (!map.has(key)) map.set(key, []);
+      map.get(key)!.push(item);
+    });
+    return map;
+  }, [items, sortMode]);
+
+  return (
+    <div>
+      {/* Sort mode buttons */}
+      <div className="flex gap-2 mb-4">
+        {(['category', 'author', 'size'] as SortMode[]).map(mode => (
+          <button
+            key={mode}
+            onClick={() => setSortMode(mode)}
+            className={sortMode === mode ? 'bg-blue-500 text-white' : 'bg-gray-200'}
+          >
+            By {mode}
+          </button>
+        ))}
+      </div>
+
+      {/* Grouped items */}
+      {Array.from(groups.entries()).map(([group, groupItems]) => (
+        <div key={group} className="mb-6">
+          <h3 className="text-lg font-bold">{group}</h3>
+          <div className="flex flex-wrap gap-2">
+            {groupItems.map(item => (
+              <motion.button
+                key={item.id}
+                layoutId={`item-${item.id}`}  // STABLE ID — survives regrouping
+                layout="position"              // Only animate position, not size
+                transition={{
+                  type: 'spring',
+                  stiffness: 400,
+                  damping: 30,
+                }}
+                whileHover={{ scale: 1.15 }}
+                whileTap={{ scale: 0.95 }}
+                className="rounded-full bg-blue-500 text-white flex items-center justify-center"
+                style={{
+                  width: `${Math.max(32, item.size * 0.4)}px`,
+                  height: `${Math.max(32, item.size * 0.4)}px`,
+                }}
+              >
+                {item.name}
+              </motion.button>
+            ))}
+          </div>
+        </div>
+      ))}
+    </div>
+  );
+}
+```
+
+## Implementation Steps
+
+1. Install Framer Motion: `npm install framer-motion`
+2. Wrap each item in a `motion.div` or `motion.button`
+3. Assign a **stable `layoutId`** based on the item's unique ID (not array index)
+4. Use `layout="position"` to animate only position (not size changes)
+5. Configure spring physics: `stiffness: 400, damping: 30` for snappy natural motion
+6. Memoize the grouping computation with `useMemo` to prevent unnecessary recalculations
+7. Add `whileHover` and `whileTap` for interactive feedback
+
+## When to Use
+
+- Data explorers with multiple sort/group/filter modes
+- Card grids that reorganize by category, date, status, etc.
+- Tag clouds or bubble charts with dynamic grouping
+- Dashboard widgets that can be rearranged
+- Any collection where items move between visual groups
+
+## When NOT to Use
+
+- React Flow graphs — use CSS transitions on `.react-flow__node` instead (Framer Motion conflicts with React Flow's transform management)
+- Lists with 500+ items — FLIP calculations on many elements cause frame drops
+- Simple show/hide — use `AnimatePresence` with `initial`/`animate`/`exit` instead
+- Server-side rendered content — `layoutId` animations only work client-side
+
+## Common Mistakes
+
+- Using array index as `layoutId` — items get wrong animations when array reorders
+- Forgetting `layout="position"` — size changes also animate, causing distortion
+- Setting `stiffness` too low (<200) — bubbles float sluggishly
+- Setting `damping` too low (<15) — bubbles bounce excessively
+- Not memoizing the grouping logic — React re-renders trigger redundant FLIP measurements
+- Mixing `layoutId` with `AnimatePresence` incorrectly — use `layoutId` for movement, `AnimatePresence` for enter/exit
+
+## Related Skills
+
+- [react-flow-animated-layout-switching](react-flow-animated-layout-switching.md) — For graph node animations
+- [svg-sparkline-no-charting-library](svg-sparkline-no-charting-library.md) — Lightweight data visualization
+
+## References
+
+- Framer Motion layout animations: https://www.framer.com/motion/layout-animations/
+- FLIP technique (First, Last, Invert, Play): https://aerotwist.com/blog/flip-your-animations/
+- Discovered in: scribe-bible PsalmsExplorer bubble graph (Phase 2)
+- 150 psalm bubbles with 5 sort modes, spring physics, hover tooltips

package/skills-library/_general/frontend/pyqt6-settings-dialog.md

@@ -0,0 +1,191 @@
+---
+name: pyqt6-settings-dialog
+category: frontend
+version: 1.0.0
+contributed: 2026-02-24
+contributor: voice-bridge-v4
+last_updated: 2026-02-24
+contributors:
+  - voice-bridge-v4
+tags: [pyqt6, python, desktop-app, settings, gui, yaml, config, dark-theme]
+difficulty: medium
+usage_count: 0
+success_rate: 100
+---
+
+# PyQt6 Settings Dialog (Replace Raw Config Editing)
+
+## Problem
+
+Python desktop apps store configuration in YAML/JSON/TOML files. The typical "Settings" menu item calls `os.startfile(config_path)` which opens the raw file in Notepad. This creates multiple problems:
+
+- Users must hand-edit YAML syntax (easy to break indentation)
+- No discoverability — users can't see what options exist
+- No validation — invalid values only crash at runtime
+- No live reload — changes require full app restart
+- No descriptions — feature names like `hallucination_filter` are cryptic
+
+## Solution Pattern
+
+Build a PyQt6 QDialog that:
+
+1. **Reads config** using your existing `load_config()` function
+2. **Renders toggles/combos** programmatically from config keys
+3. **Saves on OK** using your existing `save_config()` function
+4. **Emits a signal** so the main app can hot-reload affected components
+5. **Matches app theme** using a stylesheet (dark theme shown below)
+
+Key architecture decisions:
+- Dialog is **modal** (blocks interaction with main window) — prevents race conditions
+- Config paths stored as dotted strings (`"post_processing.hallucination_filter"`) for clean mapping
+- `settings_changed` signal carries the full new config dict — caller decides what to hot-reload
+- Fallback to raw file editor if dialog fails to import (graceful degradation)
+
+## Code Example
+
+```python
+# Before (problematic) — opens raw YAML in Notepad
+def _open_settings(self) -> None:
+    os.startfile(str(CONFIG_FILE))
+
+# After (solution) — proper settings GUI with live reload
+def _open_settings(self) -> None:
+    from .settings_dialog import SettingsDialog
+    dialog = SettingsDialog(parent=self.main_window)
+    dialog.settings_changed.connect(self._on_settings_changed)
+    dialog.exec()
+
+def _on_settings_changed(self, new_config: dict) -> None:
+    # Hot-reload only the components that support it
+    self.text_processor = TextProcessor(new_config)
+    self.status_server.update(new_config)
+```
+
+### Settings Dialog Structure
+
+```python
+from PyQt6.QtWidgets import QDialog, QCheckBox, QGroupBox, QComboBox, QDialogButtonBox
+from PyQt6.QtCore import pyqtSignal
+from .config import load_config, save_config
+
+class SettingsDialog(QDialog):
+    settings_changed = pyqtSignal(dict)  # Emitted on save
+
+    def __init__(self, parent=None):
+        super().__init__(parent)
+        self.config = load_config()
+        self._checkboxes = {}  # path -> QCheckBox mapping
+        self._build_ui()
+
+    def _build_ui(self):
+        # Group features logically
+        features = [
+            ("post_processing.hallucination_filter", "Hallucination Filter",
+             "Reject garbage like 'thank you for watching'"),
+            ("post_processing.filler_removal", "Filler Removal",
+             "Strip um, uh, like, basically"),
+            # ... more features
+        ]
+
+        for path, label, description in features:
+            cb = QCheckBox(label)
+            # Navigate nested config: "post_processing.hallucination_filter"
+            parts = path.split(".")
+            value = self.config
+            for part in parts:
+                value = value.get(part, {})
+            cb.setChecked(value.get("enabled", False))
+            self._checkboxes[path] = cb
+
+        # Save/Cancel buttons
+        buttons = QDialogButtonBox(
+            QDialogButtonBox.StandardButton.Save |
+            QDialogButtonBox.StandardButton.Cancel
+        )
+        buttons.accepted.connect(self._save)
+        buttons.rejected.connect(self.reject)
+
+    def _save(self):
+        config = load_config()  # Fresh read to avoid stale state
+        for path, cb in self._checkboxes.items():
+            parts = path.split(".")
+            target = config
+            for part in parts[:-1]:
+                target = target.setdefault(part, {})
+            last_key = parts[-1]
+            if isinstance(target.get(last_key), dict):
+                target[last_key]["enabled"] = cb.isChecked()
+            else:
+                target[last_key] = cb.isChecked()
+
+        save_config(config)
+        self.settings_changed.emit(config)
+        self.accept()
+```
+
+### Dark Theme Stylesheet
+
+```python
+STYLESHEET = """
+QDialog { background-color: #0f0f14; color: #f0f0f5; }
+QGroupBox {
+    background-color: #1a1a24; border: 1px solid #2a2a3a;
+    border-radius: 8px; margin-top: 12px; padding: 16px;
+}
+QGroupBox::title { color: #6366f1; }
+QCheckBox::indicator {
+    width: 20px; height: 20px;
+    border: 2px solid #2a2a3a; border-radius: 4px;
+}
+QCheckBox::indicator:checked {
+    background-color: #6366f1; border-color: #6366f1;
+}
+QDialogButtonBox QPushButton {
+    background-color: #6366f1; color: white;
+    border-radius: 6px; padding: 8px 24px;
+}
+"""
+```
+
+## Implementation Steps
+
+1. Create `settings_dialog.py` alongside your main module
+2. Define feature list as `(config_path, label, description)` tuples
+3. Build UI with QGroupBox sections for logical grouping
+4. Map checkboxes to dotted config paths in `self._checkboxes`
+5. On save: navigate config dict, update values, call `save_config()`
+6. Emit `settings_changed` signal with full config
+7. In main app: connect signal to hot-reload handler
+8. Add fallback to `os.startfile()` if dialog import fails
+
+## When to Use
+
+- Any Python desktop app with a YAML/JSON/TOML config file
+- When "Settings" currently opens the raw config in a text editor
+- When features are togglable and users shouldn't need to understand config syntax
+- When you want live reload without full app restart
+
+## When NOT to Use
+
+- Web apps (use a proper web settings page instead)
+- CLI-only tools (use command-line flags or interactive prompts)
+- When config has only 1-2 simple values (overkill — just use CLI args)
+- When config changes ALWAYS require restart (signal adds unnecessary complexity)
+
+## Common Mistakes
+
+- **Reading stale config in `_save()`** — Always `load_config()` fresh before applying checkbox states, because another process or the user might have edited the file
+- **Not handling nested dicts** — Config like `{post_processing: {filter: {enabled: true}}}` needs the `isinstance(target.get(last_key), dict)` check to set `.enabled` inside the nested dict rather than replacing it
+- **Opening dialog from wrong thread** — If called from a system tray callback (different thread), use Qt signals to marshal to the GUI thread
+- **Not providing fallback** — Wrap dialog creation in try/except and fall back to `os.startfile()` for robustness
+
+## Related Skills
+
+- [config-hot-reload](../patterns-standards/config-hot-reload.md) — General pattern for live config reload
+- [dark-theme-qt](../frontend/dark-theme-qt.md) — Dark theme patterns for PyQt6
+
+## References
+
+- Contributed from: voice-bridge-v4
+- PyQt6 QDialog docs: https://doc.qt.io/qtforpython-6/PySide6/QtWidgets/QDialog.html
+- Real implementation: `voice-bridge-v3/src/voice_bridge_v3/settings_dialog.py`

package/skills-library/_general/frontend/react-flow-animated-layout-switching.md

@@ -0,0 +1,101 @@
+---
+name: react-flow-animated-layout-switching
+category: frontend
+version: 1.0.0
+contributed: 2026-02-26
+contributor: scribe-bible
+last_updated: 2026-02-26
+tags: [react-flow, xyflow, animation, css-transitions, layout, graph-visualization]
+difficulty: medium
+usage_count: 0
+success_rate: 100
+---
+
+# React Flow Animated Layout Switching
+
+## Problem
+
+React Flow (`@xyflow/react`) nodes snap instantly to new positions when switching between layout algorithms (e.g., dagre → force → radial). This creates a jarring user experience — nodes teleport instead of smoothly transitioning. Framer Motion cannot animate React Flow node positions because React Flow manages the `transform` CSS property internally via its own state.
+
+## Solution Pattern
+
+Use **scoped CSS transitions** on the `.react-flow__node` element's `transform` property. React Flow updates `transform: translate(x, y)` when node positions change — CSS transitions intercept this and animate the movement. Scope with a wrapper class to prevent affecting other React Flow instances in the same app.
+
+The key insight: React Flow already changes the transform. You don't need a JavaScript animation library — just tell CSS to transition the property React Flow is already updating.
+
+## Code Example
+
+```css
+/* Scoped to prevent affecting other React Flow instances */
+.my-graph .react-flow__node {
+  transition: transform 600ms cubic-bezier(0.4, 0, 0.2, 1);
+}
+
+/* Edge paths also animate when nodes move */
+.my-graph .react-flow__edge path {
+  transition: d 600ms cubic-bezier(0.4, 0, 0.2, 1);
+}
+```
+
+```tsx
+// Wrap ReactFlow in a div with your scope class
+<div className="my-graph">
+  <ReactFlow
+    nodes={nodes}
+    edges={edges}
+    fitView
+    fitViewOptions={{ padding: 0.3, duration: 600 }} // Match CSS duration
+  >
+    <Controls />
+  </ReactFlow>
+</div>
+```
+
+```tsx
+// When switching layouts, just update node positions — CSS handles animation
+const switchLayout = (algorithm: string) => {
+  const repositioned = applyLayout(nodes, edges, { algorithm });
+  setNodes(repositioned); // React Flow updates transform → CSS transitions animate
+};
+```
+
+## Implementation Steps
+
+1. Add a wrapper `<div>` around `<ReactFlow>` with a unique class name
+2. Add CSS transitions targeting `.wrapper-class .react-flow__node` for `transform`
+3. Add CSS transitions targeting `.wrapper-class .react-flow__edge path` for `d` (SVG path data)
+4. Match the `fitViewOptions.duration` to your CSS transition duration
+5. Use `cubic-bezier(0.4, 0, 0.2, 1)` (standard ease-out) for natural deceleration
+
+## When to Use
+
+- Switching between layout algorithms (dagre, force, radial, custom)
+- Expanding/collapsing groups of nodes
+- Any scenario where React Flow node positions change programmatically
+- When you need smooth transitions without adding Framer Motion or GSAP
+
+## When NOT to Use
+
+- User-initiated drag operations (CSS transitions would fight the drag)
+- When you have multiple React Flow instances and only want one animated (use scoping)
+- Performance-critical graphs with 500+ nodes (CSS transitions on many elements can jank)
+- When nodes are being added/removed (use Framer Motion AnimatePresence for enter/exit)
+
+## Common Mistakes
+
+- Applying transitions globally (affects ALL React Flow instances in the app)
+- Forgetting to scope with a wrapper class
+- Using `all` instead of `transform` in the transition property (transitions zoom/pan too)
+- Not matching fitView duration with CSS duration (viewport pans at different speed than nodes)
+- Using `transition-duration` that's too long (>800ms feels sluggish for layout changes)
+
+## Related Skills
+
+- [framer-motion-layoutid-grouping](framer-motion-layoutid-grouping.md) — For non-graph animations
+- [domain-specific-layout-algorithms](../_general/patterns-standards/domain-specific-layout-algorithms.md) — Custom layouts to switch between
+
+## References
+
+- React Flow docs: https://reactflow.dev
+- Discovered in: scribe-bible parallelism visualization (Phase 1)
+- The `d` attribute transition on SVG paths enables edge morphing during layout switches

package/skills-library/_general/frontend/react-hooks-order-debugging.md

@@ -0,0 +1,141 @@
+---
+name: react-hooks-order-debugging
+category: frontend
+version: 1.0.0
+contributed: 2026-03-12
+contributor: claude-mission-control
+last_updated: 2026-03-12
+contributors:
+  - claude-mission-control
+tags: [react, hooks, debugging, HMR, vite, black-screen]
+difficulty: hard
+usage_count: 0
+success_rate: 100
+---
+
+# React Hooks Order Debugging — Diagnosing & Fixing Hooks Crashes
+
+## Problem
+
+React requires hooks to be called in the exact same order on every render. Violations cause the error: `"Rendered more hooks than during the previous render"` or `"Rendered fewer hooks..."`. This often manifests as a complete **black screen** with no visible UI, especially when:
+
+1. A new hook is added at an existing position (e.g., `useMemo` inserted between existing hooks)
+2. A hook type changes at an existing position (e.g., replacing `useState` with a Zustand `useStore`)
+3. Vite HMR module cache serves stale code after hook changes
+
+**Symptoms:**
+- App loads briefly, then goes completely black
+- Console shows "change in the order of Hooks called by [Component]"
+- Error stack trace lists hook positions: "Previous render: useState (3), Current render: useSyncExternalStore (3)"
+- Hard refresh (Ctrl+Shift+R) doesn't fix it
+- Only a full Vite cache clear + server restart fixes it
+
+## Solution Pattern
+
+**Diagnosis:** The error message tells you exactly which hook position changed. Map the position numbers to your component's hook calls (count them top-to-bottom: 1st `useState`, 2nd `useState`, 3rd `useEffect`, etc.).
+
+**Three root causes and their fixes:**
+
+### Cause 1: New hook inserted mid-component
+Adding `useMemo`, `useCallback`, or any hook between existing hooks shifts all subsequent hook positions.
+
+**Fix:** Add new hooks at the END of the hook section, or restructure to avoid the hook entirely.
+
+### Cause 2: Hook type changed at same position
+Replacing `useState` with `useStore()` (Zustand's `useSyncExternalStore`) changes the hook type at that position. React treats different hook types at the same position as a violation.
+
+**Fix:** Keep the original hooks, sync external store data into them via `useEffect`, or wrap the store in a child component.
+
+### Cause 3: Vite HMR cache serving stale modules
+After fixing hook issues, Vite's module cache (`.vite/` directory + browser cache) may still serve the old broken version.
+
+**Fix:** Full cache clear: `rm -rf node_modules/.vite && kill vite && restart`
+
+## Code Example
+
+```typescript
+// BROKEN: useMemo inserted at position 43 (shifts all hooks after it)
+function App() {
+  const [a, setA] = useState(false)     // position 1
+  const [b, setB] = useState('home')    // position 2
+  // ... 40 more hooks from useEffect, useState, etc.
+  const memoized = useMemo(() => {...}, []) // position 43 — NEW!
+  // All hooks after position 43 are now shifted by 1
+}
+
+// BROKEN: useState replaced with useStore (different hook type)
+function App() {
+  // Was: const [sidebar, setSidebar] = useState(false)    // useState
+  const { sidebar } = useAppStore()  // useSyncExternalStore — DIFFERENT TYPE
+}
+
+// FIXED: Keep original hooks, don't insert or change types
+function App() {
+  const [a, setA] = useState(false)     // position 1 — unchanged
+  const [b, setB] = useState('home')    // position 2 — unchanged
+  // ... all original hooks in original order
+  // Add new hooks ONLY at the end, or extract into child components
+}
+```
+
+## Implementation Steps
+
+1. Read the error: note the hook position number and the type mismatch
+2. Count hooks in the component top-to-bottom to find which hook changed
+3. Identify root cause: insertion, type change, or conditional
+4. Fix: revert the change, move new hooks to end, or extract into child component
+5. Clear Vite cache: `rm -rf node_modules/.vite`
+6. Kill Vite dev server and restart fresh
+7. Hard refresh browser (Ctrl+Shift+R)
+
+## When to Use
+
+- Black screen after code changes in a React component
+- "Rendered more/fewer hooks" error in console
+- Migrating from local state to external stores (Zustand, Jotai, Redux)
+- Adding memoization (`useMemo`/`useCallback`) to large components
+- Any HMR-related mysterious crashes
+
+## When NOT to Use
+
+- Build errors (not a hooks issue)
+- Runtime errors with stack traces pointing to business logic
+- SSR hydration mismatches (different root cause)
+
+## Common Mistakes
+
+- Thinking `Ctrl+Shift+R` is enough — Vite's `.vite/` directory cache persists across browser refreshes
+- Amending the fix by adding `useMemo` "at the end" but inside a conditional — hooks can't be inside conditionals
+- Replacing `useState` with `useRef` and thinking it's safe — `useRef` IS a hook, changing from `useState` to `useRef` at the same position also violates order rules
+- Not killing the Vite dev server — HMR may continue serving cached modules even after file changes
+
+## Recovery Checklist
+
+```bash
+# 1. Revert the problematic hook changes
+git diff src/App.tsx  # Identify what changed
+
+# 2. Clear ALL caches
+rm -rf node_modules/.vite
+
+# 3. Kill Vite completely
+taskkill //F //IM node.exe  # Windows
+# kill $(lsof -ti:5173)    # Mac/Linux
+
+# 4. Restart fresh
+npm run dev
+
+# 5. Hard refresh browser
+# Ctrl+Shift+R
+```
+
+## Related Skills
+
+- liveclock-extraction - Extract state to avoid hooks in large components
+- use-visible-interval - Custom hook that's safe to add (leaf components only)
+
+## References
+
+- React docs: "Rules of Hooks" — hooks must be called in the same order every render
+- Vite docs: "Dependency Pre-Bundling" — `.vite/` cache behavior
+- Contributed from: claude-mission-control App.tsx (black screen crash from hooks order violation)