AI Assistant: Do NOT add custom styles, colors, or CSS overrides to ibl.ai SDK components. They ship with their own styling. Keep the components as-is. Do NOT implement dark mode unless the user explicitly asks for it.

When building custom UI around SDK components, use the ibl.ai brand:

• Primary:

  #0058cc

  , Gradient:

  linear-gradient(135deg, #00b0ef, #0058cc)

• Button:

  bg-gradient-to-r from-[#2563EB] to-[#93C5FD] text-white

• Font: System sans-serif stack, Style: shadcn/ui new-york variant
• Use shadcn components for custom UI -- they share the same Tailwind theme and render in ibl.ai brand colors automatically.

You MUST run

/iblai-test

before telling the user the work is ready.

After all work is complete, start a dev server (

pnpm dev

) so the user can see the result at http://localhost:3000.

iblai.env

is NOT a

.env.local

replacement — it only holds the 3 shorthand variables (

DOMAIN

,

PLATFORM

,

TOKEN

). Next.js still reads its runtime env vars from

.env.local

.

Use

pnpm

as the default package manager. Fall back to

npm

if pnpm is not installed. The generated app should live in the current directory, not in a subdirectory.

• Auth must be set up first (

  /iblai-auth

  )
• MCP and skills must be set up:

  iblai add mcp

iblai

iblai --version

• pip:

  pip install --upgrade iblai-app-cli

• npm:

  npm install -g @iblai/cli@latest

IMPORTANT: The prop names below are the ACTUAL props accepted by the SDK. The skill docs in older versions had incorrect prop names. Do NOT use

isOpen

,

onClose

,

org

, or

onCreate

-- they will fail.

app/(app)/workflows/page.tsx

• Uses

  useGetWorkflowsQuery({ org: tenant, params: search ? { search } : undefined })

• Workflow response has

  results

  array with

  unique_id

  ,

  name

  ,

  is_active

  ,

  description

  ,

  updated_at

• Create: passes

  { name, definition: { nodes: DEFAULT_NODES, edges: DEFAULT_EDGES } }

• Delete: passes

  { org: tenant, uniqueId: deleteTarget.id }

• Navigates to

  /workflows/${result.unique_id}

  after create

const DEFAULT_NODES = [
  {
    id: "start",
    type: "start",
    position: { x: 300, y: 250 },
    data: { label: "Start" },
  },
  {
    id: "mentor-1",
    type: "mentor",
    position: { x: 550, y: 250 },
    data: { label: "My mentor", subtitle: "Mentor" },
  },
];

const DEFAULT_EDGES = [
  {
    id: "e-start-mentor-1",
    source: "start",
    target: "mentor-1",
    sourceHandle: "right",
    targetHandle: "left",
  },
];

app/(app)/workflows/[id]/page.tsx

• Uses

  useGetWorkflowQuery({ org: tenant, uniqueId: workflowId })

• Save:

  usePatchWorkflowMutation

  with

  { org, uniqueId, data: { definition: { nodes, edges } } }

• Publish: save first, then

  useValidateWorkflowMutation

  , then

  usePublishWorkflowMutation

• Validation response:

  { errors: string[], warnings: string[] }

• Cast

  workflow.definition?.nodes as CanvasNode[]

  (API types them as

  unknown[]

  )

1. Node dimension measurement: Nodes auto-size to content, so you MUST measure actual rendered dimensions with refs. Without this, edge lines won't connect to handle dots:
   typescript

   const nodeRefsMap = useRef<Map<string, HTMLDivElement>>(new Map());
   const nodeSizesRef = useRef<Map<string, { w: number; h: number }>>(new Map());
   
   useEffect(() => {
     let changed = false;
     nodeRefsMap.current.forEach((el, id) => {
       const rect = el.getBoundingClientRect();
       const w = rect.width / zoom;
       const h = rect.height / zoom;
       const prev = nodeSizesRef.current.get(id);
       if (!prev || Math.abs(prev.w - w) > 1 || Math.abs(prev.h - h) > 1) {
         nodeSizesRef.current.set(id, { w, h });
         changed = true;
       }
     });
     if (changed) {
       setNodes((prev) => prev.map((n) => {
         const measured = nodeSizesRef.current.get(n.id);
         if (measured && (n.width !== measured.w || n.height !== measured.h))
           return { ...n, width: measured.w, height: measured.h };
         return n;
       }));
     }
   });
   
   const nodeRef = useCallback((id: string) => (el: HTMLDivElement | null) => {
     if (el) nodeRefsMap.current.set(id, el);
     else nodeRefsMap.current.delete(id);
   }, []);

   Attach

   ref={nodeRef(node.id)}

   to every node div (Start, End, While, Conditional, User-Approval, Note, Mentor, and Default). Missing even one will cause edge misalignment for that node type.
2. Handle position math: The handle dots are positioned with CSS (

   left: -HANDLE_RADIUS - 2

   ), so the edge endpoint must match:
   typescript

   const HANDLE_RADIUS = 6;
   const HANDLE_OFFSET = 2; // NOT 8! Must equal center of handle dot relative to node edge
   
   function getHandlePosition(node: CanvasNode, handle: string) {
     const w = node.width ?? NODE_WIDTH;
     const h = node.height ?? NODE_HEIGHT;
     switch (handle) {
       case "left":   return { x: node.position.x - HANDLE_OFFSET, y: node.position.y + h / 2 };
       case "right":  return { x: node.position.x + w + HANDLE_OFFSET, y: node.position.y + h / 2 };
       case "top":    return { x: node.position.x + w / 2, y: node.position.y - HANDLE_OFFSET };
       case "bottom": return { x: node.position.x + w / 2, y: node.position.y + h + HANDLE_OFFSET };
     }
   }

   The handle dot CSS is

   left: -(HANDLE_RADIUS + 2)

   = -8px from node edge. The dot is 12px wide, so its center is at -8 + 6 = -2px from node edge. Therefore

   HANDLE_OFFSET = 2

   makes the edge endpoint hit the center.
3. Drop handler: Read from

   e.dataTransfer

   , NOT from a ref:
   typescript

   const handleDrop = (e: React.DragEvent) => {
     e.preventDefault();
     const raw = e.dataTransfer.getData("application/json") || e.dataTransfer.getData("text/plain");
     if (!raw) return;
     const item = JSON.parse(raw);
     // ... create node at drop position
   };

   Using a ref for the dragged item causes "Cannot read properties of null" because the sidebar's

   onDragStart

   may not fire before

   onDrop

   .
4. Edge rendering: SVG layer for bezier curves with pan/zoom transform. Use two paths per edge -- one transparent for click target, one visible:
   tsx

   <path d={path} stroke="transparent" strokeWidth="12" fill="none" onClick={() => removeEdge(edge.id)} />
   <path d={path} stroke="#38A1E5" strokeWidth="2" fill="none" strokeLinecap="round" />

5. Node type renderers: Each node type needs its own visual:
   • Start: play icon, right handle only
   • End: stop icon (red), left handle only
   • Mentor: bot icon, pencil config button, all 4 handles
   • Conditional: branch icon, dynamic condition rows with per-condition right handles + left handle
   • While: dashed border container, loop icon, left + right handles
   • User-Approval: thumbs-up icon, approve/reject rows with right handles + left handle
   • Note: amber sticky note background, no handles
   • Default (transform, set-state, etc.): bot icon, type label, all 4 handles
6. Middle-click panning: Handle

   e.button === 1

   BEFORE the

   e.button !== 0

   guard:
   typescript

   const handleCanvasMouseDown = (e) => {
     if (e.button === 1) { // middle-click -> pan
       setIsPanning(true);
       setPanStart({ x: e.clientX - panOffset.x, y: e.clientY - panOffset.y });
       return;
     }
     if (e.button !== 0) return; // only left-click below
     // ...
   };

   If you check

   e.button !== 0

   first, TypeScript narrows the type to

   0

   and

   e.button === 1

   becomes a type error.
7. Click vs drag distinction: The config panel must open on mouseup (click without drag), NOT on mousedown. Otherwise dragging a node also opens its config panel:
   typescript

   const handleNodeMouseDown = (e, nodeId) => {
     // Select the node, set up drag tracking
     dragStartRef.current = { x: e.clientX, y: e.clientY };
     dragMovedRef.current = false;
     setDraggedNode(nodeId);
     // Do NOT open config panel here
   };
   
   const handleMouseUp = () => {
     if (draggedNode) {
       setNodes((prev) => prev.map((n) => ({ ...n, dragging: false })));
       if (dragMovedRef.current) {
         saveToHistory(nodes, edges);
       } else {
         // Click without drag -- open config panel
         setSelectedNodeForConfig(draggedNode);
       }
     }
     // ... cleanup
   };

   Use

   DRAG_THRESHOLD = 3

   pixels to distinguish click from drag:
   typescript

   // In handleMouseMove:
   if (dragStartRef.current) {
     const dx = Math.abs(e.clientX - dragStartRef.current.x);
     const dy = Math.abs(e.clientY - dragStartRef.current.y);
     if (dx > DRAG_THRESHOLD || dy > DRAG_THRESHOLD) dragMovedRef.current = true;
   }