@hailer/mcp 0.0.5 → 0.0.6

package/.claude/skills/MCP-scaffold-hailer-app-skill/SKILL.md

@@ -638,6 +638,42 @@ npm run dev
 
 App is already created in Hailer, just needs server running.
 
+### Infinite Loop When Loading Data
+
+**Problem:** App keeps re-fetching data infinitely, causing performance issues.
+
+**Cause:** Using `hailer` object in useEffect dependencies. The `hailer` object from `useHailer()` changes reference on every render.
+
+**Solution:**
+```typescript
+// ❌ WRONG - causes infinite loop
+useEffect(() => {
+  if (!hailer) return;
+  hailer.activity.list(...);
+}, [hailer]); // hailer changes every render!
+
+// ✅ CORRECT - use `inside` and access hailer from window
+useEffect(() => {
+  if (!inside) return;
+  const hailer = (window as any).hailerApiInstance;
+  if (!hailer) return;
+  hailer.activity.list(...);
+}, [inside]); // inside is a stable boolean
+```
+
+### Chakra UI Table Not Showing Text
+
+**Problem:** Table rows render but text is invisible/white.
+
+**Cause:** CSS inheritance issues when running inside Hailer iframe.
+
+**Solution:** Add explicit `color="black"` to Td components:
+```typescript
+<Tr key={activity._id} bg="white">
+  <Td color="black">{value}</Td>
+</Tr>
+```
+
 ### CORS Error When Opening App in Hailer
 
 **Problem:** Browser console shows "Access to fetch at 'http://localhost:3000/manifest.json' from origin 'https://next.hailer.com' has been blocked by CORS policy"
@@ -807,8 +843,10 @@ const competition = match.competition;  // undefined
 
 ### Complete Working Example
 
+**⚠️ CRITICAL: Do NOT use `hailer` in useEffect dependencies - it causes infinite loops!**
+
 ```typescript
-import { useEffect, useState } from 'react';
+import { useEffect, useState, useRef } from 'react';
 import useHailer from './hailer/use-hailer';
 
 // Define your activity interface based on workflow fields
@@ -816,7 +854,7 @@ interface Activity {
   _id: string;
   name: string;
   fields?: {
-    [fieldId: string]: unknown;  // Fields are keyed by field IDs
+    [fieldId: string]: { type: string; value: unknown };  // Fields have type and value
   };
 }
 
@@ -829,16 +867,23 @@ export default function ActivityList({ workflowId, phaseId }: Props) {
   const { hailer, inside } = useHailer();
   const [activities, setActivities] = useState<Activity[]>([]);
   const [loading, setLoading] = useState(true);
+  const loadedRef = useRef(false);
 
   useEffect(() => {
-    if (!hailer || !inside) return;
+    // ✅ Use `inside` as trigger - it's stable
+    if (!inside) return;
+    if (loadedRef.current) return;
+
+    // ✅ Access hailer from window to avoid reference changes
+    const hailerApi = (window as any).hailerApiInstance;
+    if (!hailerApi) return;
 
     async function fetchActivities() {
       try {
         // ✅ CORRECT: activity.list with separate parameters
-        const result = await hailer.activity.list(
-          workflowId,  // Pass workflow ID as prop
-          phaseId,     // Pass phase ID as prop
+        const result = await hailerApi.activity.list(
+          workflowId,
+          phaseId,
           {
             sortBy: 'created',
             sortOrder: 'asc',
@@ -847,6 +892,7 @@ export default function ActivityList({ workflowId, phaseId }: Props) {
         );
 
         setActivities(result || []);
+        loadedRef.current = true;
       } catch (err) {
         console.error('Failed to fetch:', err);
       } finally {
@@ -855,7 +901,7 @@ export default function ActivityList({ workflowId, phaseId }: Props) {
     }
 
     fetchActivities();
-  }, [hailer, inside, workflowId, phaseId]);
+  }, [inside, workflowId, phaseId]); // ✅ NO hailer in deps!
 
   if (loading) return <div>Loading...</div>;
 
@@ -864,7 +910,7 @@ export default function ActivityList({ workflowId, phaseId }: Props) {
       {activities.map((activity) => (
         <div key={activity._id}>
           <h3>{activity.name}</h3>
-          {/* Access fields via field IDs - get IDs from workflow schema */}
+          {/* Access fields: activity.fields?.[fieldId]?.value */}
         </div>
       ))}
     </div>
@@ -1119,20 +1165,30 @@ ReactDOM.createRoot(document.getElementById('root')!).render(
 
 **If you skip this, the app will render with NO STYLES!**
 
-## Data Loading Pattern (SIMPLE)
+## Data Loading Pattern (CRITICAL - PREVENTS INFINITE LOOPS)
+
+**⚠️ THE `hailer` OBJECT CHANGES ON EVERY RENDER!** Using `hailer` in useEffect dependencies causes infinite loops.
 
-Use this SIMPLE pattern - no complex refs needed:
+Use `inside` boolean as the trigger and access hailer from window:
 
 \`\`\`typescript
-import { useState, useEffect } from 'react';
+import { useState, useEffect, useRef } from 'react';
 
-function useMyData(hailer: HailerApi | undefined) {
+// Hook takes `inside` boolean, NOT hailer object
+function useMyData(inside: boolean) {
   const [data, setData] = useState([]);
   const [loading, setLoading] = useState(true);
   const [error, setError] = useState<string | null>(null);
   const [refreshTrigger, setRefreshTrigger] = useState(0);
+  const loadedRef = useRef(false);
 
   useEffect(() => {
+    // Use `inside` as trigger - it's a stable boolean
+    if (!inside) return;
+    if (loadedRef.current && refreshTrigger === 0) return;
+
+    // Access hailer from window to avoid reference changes
+    const hailer = (window as any).hailerApiInstance;
     if (!hailer) return;
 
     async function loadData() {
@@ -1148,6 +1204,7 @@ function useMyData(hailer: HailerApi | undefined) {
         );
 
         setData(result || []);
+        loadedRef.current = true;
       } catch (err) {
         setError(err instanceof Error ? err.message : 'Failed to load');
       } finally {
@@ -1156,15 +1213,35 @@ function useMyData(hailer: HailerApi | undefined) {
     }
 
     loadData();
-  }, [hailer, refreshTrigger]);
+  }, [inside, refreshTrigger]); // ✅ inside is stable, hailer is NOT
 
-  const refresh = () => setRefreshTrigger(prev => prev + 1);
+  const refresh = () => {
+    loadedRef.current = false;
+    setRefreshTrigger(prev => prev + 1);
+  };
 
   return { data, loading, error, refresh };
 }
 \`\`\`
 
-**DO NOT use useCallback/useRef complexity - it causes infinite loops!**
+**In App.tsx, pass `inside` not `hailer`:**
+\`\`\`typescript
+export default function App() {
+  const { hailer, inside } = useHailer();
+  const { data, loading, error } = useMyData(inside); // ✅ Pass inside, not hailer
+
+  if (!hailer || !inside) {
+    return <Spinner />;
+  }
+  // ...
+}
+\`\`\`
+
+**KEY RULES:**
+1. ❌ NEVER use `hailer` in useEffect dependencies - causes infinite loops
+2. ✅ Use `inside` boolean as the stable trigger
+3. ✅ Access hailer via `(window as any).hailerApiInstance` inside useEffect
+4. ✅ Use `loadedRef` to prevent duplicate loads
 
 ## Field Access Pattern
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hailer/mcp",
-  "version": "0.0.5",
+  "version": "0.0.6",
   "config": {
     "docker": {
       "registry": "registry.gitlab.com/hailer-repos/hailer-mcp"