Enhance HRIStudio with immersive experiment designer and comprehensive documentation updates

- Introduced a new immersive experiment designer using React Flow, providing a professional-grade visual flow editor for creating experiments.
- Added detailed documentation for the flow designer connections and ordering system, emphasizing its advantages and implementation details.
- Updated existing documentation to reflect the latest features and improvements, including a streamlined README and quick reference guide.
- Consolidated participant type definitions into a new file for better organization and clarity.

Features:
- Enhanced user experience with a node-based interface for experiment design.
- Comprehensive documentation supporting new features and development practices.

Breaking Changes: None - existing functionality remains intact.

src/app/(dashboard)/analytics/page.tsx

@@ -1,52 +1,50 @@
-"use client"
+"use client";
 
-import * as React from "react"
-import { 
-  BarChart3, 
-  TrendingUp, 
-  TrendingDown, 
-  Activity, 
+import {
+  Activity,
+  BarChart3,
   Calendar,
+  Download,
   Filter,
-  Download
-} from "lucide-react"
+  TrendingDown,
+  TrendingUp,
+} from "lucide-react";
 
-import { Button } from "~/components/ui/button"
+import { StudyGuard } from "~/components/dashboard/study-guard";
+import { Button } from "~/components/ui/button";
 import {
   Card,
   CardContent,
   CardDescription,
   CardHeader,
   CardTitle,
-} from "~/components/ui/card"
-import { Badge } from "~/components/ui/badge"
+} from "~/components/ui/card";
 import {
   Select,
   SelectContent,
   SelectItem,
   SelectTrigger,
   SelectValue,
-} from "~/components/ui/select"
-import { StudyGuard } from "~/components/dashboard/study-guard"
+} from "~/components/ui/select";
 
 // Mock chart component - replace with actual charting library
 function MockChart({ title, data }: { title: string; data: number[] }) {
-  const maxValue = Math.max(...data)
-  
+  const maxValue = Math.max(...data);
+
   return (
     <div className="space-y-2">
       <h4 className="text-sm font-medium">{title}</h4>
-      <div className="flex items-end space-x-1 h-32">
+      <div className="flex h-32 items-end space-x-1">
         {data.map((value, index) => (
-          <div 
+          <div
             key={index}
-            className="bg-primary rounded-t flex-1 min-h-[4px]"
+            className="bg-primary min-h-[4px] flex-1 rounded-t"
             style={{ height: `${(value / maxValue) * 100}%` }}
           />
         ))}
       </div>
     </div>
-  )
+  );
 }
 
 function AnalyticsOverview() {
@@ -62,7 +60,7 @@ function AnalyticsOverview() {
     {
       title: "Avg Trial Duration",
       value: "24.5m",
-      change: "-3%", 
+      change: "-3%",
       trend: "down",
       description: "vs last month",
       icon: Calendar,
@@ -71,7 +69,7 @@ function AnalyticsOverview() {
       title: "Completion Rate",
       value: "94.2%",
       change: "+2.1%",
-      trend: "up", 
+      trend: "up",
       description: "vs last month",
       icon: TrendingUp,
     },
@@ -80,29 +78,33 @@ function AnalyticsOverview() {
       value: "87.3%",
       change: "+5.4%",
       trend: "up",
-      description: "vs last month", 
+      description: "vs last month",
       icon: BarChart3,
     },
-  ]
+  ];
 
   return (
     <div className="grid gap-4 md:grid-cols-2 lg:grid-cols-4">
       {metrics.map((metric) => (
         <Card key={metric.title}>
           <CardHeader className="flex flex-row items-center justify-between space-y-0 pb-2">
-            <CardTitle className="text-sm font-medium">{metric.title}</CardTitle>
-            <metric.icon className="h-4 w-4 text-muted-foreground" />
+            <CardTitle className="text-sm font-medium">
+              {metric.title}
+            </CardTitle>
+            <metric.icon className="text-muted-foreground h-4 w-4" />
           </CardHeader>
           <CardContent>
             <div className="text-2xl font-bold">{metric.value}</div>
-            <div className="flex items-center space-x-2 text-xs text-muted-foreground">
-              <span className={`flex items-center ${
-                metric.trend === "up" ? "text-green-600" : "text-red-600"
-              }`}>
+            <div className="text-muted-foreground flex items-center space-x-2 text-xs">
+              <span
+                className={`flex items-center ${
+                  metric.trend === "up" ? "text-green-600" : "text-red-600"
+                }`}
+              >
                 {metric.trend === "up" ? (
-                  <TrendingUp className="h-3 w-3 mr-1" />
+                  <TrendingUp className="mr-1 h-3 w-3" />
                 ) : (
-                  <TrendingDown className="h-3 w-3 mr-1" />
+                  <TrendingDown className="mr-1 h-3 w-3" />
                 )}
                 {metric.change}
               </span>
@@ -112,13 +114,13 @@ function AnalyticsOverview() {
         </Card>
       ))}
     </div>
-  )
+  );
 }
 
 function ChartsSection() {
-  const trialData = [12, 19, 15, 27, 32, 28, 35, 42, 38, 41, 37, 44]
-  const participantData = [8, 12, 10, 15, 18, 16, 20, 24, 22, 26, 23, 28]
-  const completionData = [85, 88, 92, 89, 94, 91, 95, 92, 96, 94, 97, 94]
+  const trialData = [12, 19, 15, 27, 32, 28, 35, 42, 38, 41, 37, 44];
+  const participantData = [8, 12, 10, 15, 18, 16, 20, 24, 22, 26, 23, 28];
+  const completionData = [85, 88, 92, 89, 94, 91, 95, 92, 96, 94, 97, 94];
 
   return (
     <div className="grid gap-4 lg:grid-cols-3">
@@ -152,20 +154,22 @@ function ChartsSection() {
         </CardContent>
       </Card>
     </div>
-  )
+  );
 }
 
 function RecentInsights() {
   const insights = [
     {
       title: "Peak Performance Hours",
-      description: "Participants show 23% better performance during 10-11 AM trials",
+      description:
+        "Participants show 23% better performance during 10-11 AM trials",
       type: "trend",
       severity: "info",
     },
     {
       title: "Attention Span Decline",
-      description: "Average attention span has decreased by 8% over the last month",
+      description:
+        "Average attention span has decreased by 8% over the last month",
       type: "alert",
       severity: "warning",
     },
@@ -178,23 +182,23 @@ function RecentInsights() {
     {
       title: "Equipment Utilization",
       description: "Robot interaction trials are at 85% capacity utilization",
-      type: "info", 
+      type: "info",
       severity: "info",
     },
-  ]
+  ];
 
   const getSeverityColor = (severity: string) => {
     switch (severity) {
       case "success":
-        return "bg-green-50 text-green-700 border-green-200"
+        return "bg-green-50 text-green-700 border-green-200";
       case "warning":
-        return "bg-yellow-50 text-yellow-700 border-yellow-200"
+        return "bg-yellow-50 text-yellow-700 border-yellow-200";
       case "info":
-        return "bg-blue-50 text-blue-700 border-blue-200"
+        return "bg-blue-50 text-blue-700 border-blue-200";
       default:
-        return "bg-gray-50 text-gray-700 border-gray-200"
+        return "bg-gray-50 text-gray-700 border-gray-200";
     }
-  }
+  };
 
   return (
     <Card>
@@ -207,18 +211,18 @@ function RecentInsights() {
       <CardContent>
         <div className="space-y-4">
           {insights.map((insight, index) => (
-            <div 
+            <div
               key={index}
-              className={`p-4 rounded-lg border ${getSeverityColor(insight.severity)}`}
+              className={`rounded-lg border p-4 ${getSeverityColor(insight.severity)}`}
             >
-              <h4 className="font-medium mb-1">{insight.title}</h4>
+              <h4 className="mb-1 font-medium">{insight.title}</h4>
               <p className="text-sm">{insight.description}</p>
             </div>
           ))}
         </div>
       </CardContent>
     </Card>
-  )
+  );
 }
 
 function AnalyticsContent() {
@@ -292,7 +296,7 @@ function AnalyticsContent() {
         </Card>
       </div>
     </div>
-  )
+  );
 }
 
 export default function AnalyticsPage() {
@@ -301,4 +305,4 @@ export default function AnalyticsPage() {
       <AnalyticsContent />
     </StudyGuard>
   );
-}
+}

src/app/(dashboard)/experiments/[id]/designer/page.tsx

@@ -20,15 +20,36 @@ export default async function ExperimentDesignerPage({
     }
 
     return (
-      <ExperimentDesignerClient
-        experiment={{
-          ...experiment,
-          description: experiment.description ?? "",
-        }}
-      />
+      <div className="fixed inset-0 z-50">
+        <ExperimentDesignerClient
+          experiment={{
+            ...experiment,
+            description: experiment.description ?? "",
+          }}
+        />
+      </div>
     );
   } catch (error) {
     console.error("Error loading experiment:", error);
     notFound();
   }
 }
+
+export async function generateMetadata({
+  params,
+}: ExperimentDesignerPageProps) {
+  try {
+    const resolvedParams = await params;
+    const experiment = await api.experiments.get({ id: resolvedParams.id });
+
+    return {
+      title: `${experiment?.name} - Flow Designer | HRIStudio`,
+      description: `Design experiment protocol for ${experiment?.name} using visual flow editor`,
+    };
+  } catch {
+    return {
+      title: "Experiment Flow Designer | HRIStudio",
+      description: "Immersive visual experiment protocol designer",
+    };
+  }
+}

src/app/(dashboard)/participants/[id]/page.tsx

@@ -1,6 +1,15 @@
 import { formatDistanceToNow } from "date-fns";
 import {
-    AlertCircle, ArrowLeft, Calendar, Edit, FileText, Mail, Play, Shield, Trash2, Users
+  AlertCircle,
+  ArrowLeft,
+  Calendar,
+  Edit,
+  FileText,
+  Mail,
+  Play,
+  Shield,
+  Trash2,
+  Users,
 } from "lucide-react";
 import Link from "next/link";
 import { notFound } from "next/navigation";
@@ -8,11 +17,11 @@ import { Alert, AlertDescription } from "~/components/ui/alert";
 import { Badge } from "~/components/ui/badge";
 import { Button } from "~/components/ui/button";
 import {
-    Card,
-    CardContent,
-    CardDescription,
-    CardHeader,
-    CardTitle
+  Card,
+  CardContent,
+  CardDescription,
+  CardHeader,
+  CardTitle,
 } from "~/components/ui/card";
 import { auth } from "~/server/auth";
 import { api } from "~/trpc/server";
@@ -42,7 +51,7 @@ export default async function ParticipantDetailPage({
 
     const userRole = session.user.roles?.[0]?.role ?? "observer";
     const canEdit = ["administrator", "researcher"].includes(userRole);
-    const canDelete = ["administrator", "researcher"].includes(userRole);
+    // canDelete removed - not used in component
 
     // Get participant's trials
     const trials = await api.trials.list({
@@ -70,7 +79,7 @@ export default async function ParticipantDetailPage({
               </div>
               <div>
                 <h1 className="text-foreground text-3xl font-bold">
-                  {participant.name || participant.participantCode}
+                  {participant.name ?? participant.participantCode}
                 </h1>
                 <p className="text-muted-foreground text-lg">
                   {participant.name
@@ -151,58 +160,59 @@ export default async function ParticipantDetailPage({
                     </h4>
                     <p className="text-sm">
                       <Link
-                        href={`/studies/${(participant.study as any)?.id}`}
+                        href={`/studies/${participant.study?.id}`}
                         className="text-primary hover:underline"
                       >
-                        {(participant.study as any)?.name}
+                        {participant.study?.name}
                       </Link>
                     </p>
                   </div>
                 </div>
 
                 {participant.demographics &&
-                  typeof participant.demographics === "object" &&
-                  Object.keys(participant.demographics).length > 0 ? (
-                    <div className="border-t pt-4">
-                      <h4 className="text-muted-foreground mb-2 text-sm font-medium">
-                        Demographics
-                      </h4>
-                      <div className="grid gap-4 md:grid-cols-2">
-                        {(participant.demographics as Record<string, any>)
-                          ?.age && (
-                          <div>
-                            <span className="text-sm font-medium">Age:</span>{" "}
-                            <span className="text-sm">
-                              {String(
-                                (
-                                  participant.demographics as Record<
-                                    string,
-                                    any
-                                  >
-                                ).age,
-                              )}
-                            </span>
-                          </div>
-                        )}
-                        {(participant.demographics as Record<string, any>)
-                          ?.gender && (
-                          <div>
-                            <span className="text-sm font-medium">Gender:</span>{" "}
-                            <span className="text-sm">
-                              {String(
-                                (
-                                  participant.demographics as Record<
-                                    string,
-                                    any
-                                  >
-                                ).gender,
-                              )}
-                            </span>
-                          </div>
-                        )}
-                      </div>
+                typeof participant.demographics === "object" &&
+                participant.demographics !== null &&
+                Object.keys(participant.demographics).length > 0 ? (
+                  <div className="border-t pt-4">
+                    <h4 className="text-muted-foreground mb-2 text-sm font-medium">
+                      Demographics
+                    </h4>
+                    <div className="grid gap-4 md:grid-cols-2">
+                      {(() => {
+                        const demo = participant.demographics as Record<
+                          string,
+                          unknown
+                        >;
+                        return (
+                          <>
+                            {demo.age && (
+                              <div>
+                                <span className="text-sm font-medium">
+                                  Age:
+                                </span>{" "}
+                                <span className="text-sm">
+                                  {typeof demo.age === "number"
+                                    ? demo.age.toString()
+                                    : String(demo.age)}
+                                </span>
+                              </div>
+                            )}
+                            {demo.gender && (
+                              <div>
+                                <span className="text-sm font-medium">
+                                  Gender:
+                                </span>{" "}
+                                <span className="text-sm">
+                                  {String(demo.gender)}
+                                </span>
+                              </div>
+                            )}
+                          </>
+                        );
+                      })()}
                     </div>
-                  ) : null}
+                  </div>
+                ) : null}
 
                 {/* Notes */}
                 {participant.notes && (
@@ -228,7 +238,9 @@ export default async function ParticipantDetailPage({
                   </CardTitle>
                   {canEdit && (
                     <Button size="sm" asChild>
-                      <Link href={`/trials/new?participantId=${resolvedParams.id}`}>
+                      <Link
+                        href={`/trials/new?participantId=${resolvedParams.id}`}
+                      >
                         Schedule Trial
                       </Link>
                     </Button>
@@ -270,13 +282,10 @@ export default async function ParticipantDetailPage({
                         <div className="text-muted-foreground flex items-center gap-4 text-sm">
                           <span className="flex items-center gap-1">
                             <Calendar className="h-4 w-4" />
-                            {(trial as any).scheduledAt
-                              ? formatDistanceToNow(
-                                  (trial as any).scheduledAt,
-                                  {
-                                    addSuffix: true,
-                                  },
-                                )
+                            {trial.createdAt
+                              ? formatDistanceToNow(new Date(trial.createdAt), {
+                                  addSuffix: true,
+                                })
                               : "Not scheduled"}
                           </span>
                           {trial.duration && (
@@ -293,11 +302,13 @@ export default async function ParticipantDetailPage({
                     <Play className="text-muted-foreground mx-auto mb-4 h-12 w-12" />
                     <h3 className="mb-2 font-medium">No Trials Yet</h3>
                     <p className="text-muted-foreground mb-4 text-sm">
-                      This participant hasn't been assigned to any trials.
+                      This participant hasn&apos;t been assigned to any trials.
                     </p>
                     {canEdit && (
                       <Button asChild>
-                        <Link href={`/trials/new?participantId=${resolvedParams.id}`}>
+                        <Link
+                          href={`/trials/new?participantId=${resolvedParams.id}`}
+                        >
                           Schedule First Trial
                         </Link>
                       </Button>
@@ -399,7 +410,9 @@ export default async function ParticipantDetailPage({
                     className="w-full justify-start"
                     asChild
                   >
-                    <Link href={`/trials/new?participantId=${resolvedParams.id}`}>
+                    <Link
+                      href={`/trials/new?participantId=${resolvedParams.id}`}
+                    >
                       <Play className="mr-2 h-4 w-4" />
                       Schedule Trial
                     </Link>
@@ -427,7 +440,7 @@ export default async function ParticipantDetailPage({
         </div>
       </div>
     );
-  } catch (_error) {
+  } catch {
     return notFound();
   }
 }

src/app/(dashboard)/studies/[id]/page.tsx

@@ -252,14 +252,14 @@ export default async function StudyDetailPage({
                     >
                       <div className="flex h-8 w-8 items-center justify-center rounded-full bg-blue-100">
                         <span className="text-sm font-medium text-blue-600">
-                          {(member.user.name || member.user.email)
+                          {(member.user.name ?? member.user.email)
                             .charAt(0)
                             .toUpperCase()}
                         </span>
                       </div>
                       <div className="min-w-0 flex-1">
                         <p className="truncate text-sm font-medium text-slate-900">
-                          {member.user.name || member.user.email}
+                          {member.user.name ?? member.user.email}
                         </p>
                         <p className="text-xs text-slate-500 capitalize">
                           {member.role}

src/app/(dashboard)/studies/[id]/participants/page.tsx

@@ -2,13 +2,13 @@
 
 import { useParams } from "next/navigation";
 import { Suspense, useEffect } from "react";
-import { ManagementPageLayout } from "~/components/ui/page-layout";
 import { ParticipantsTable } from "~/components/participants/ParticipantsTable";
+import { ManagementPageLayout } from "~/components/ui/page-layout";
 import { useActiveStudy } from "~/hooks/useActiveStudy";
 
 export default function StudyParticipantsPage() {
   const params = useParams();
-  const studyId = params.id as string;
+  const studyId = typeof params.id === "string" ? params.id : "";
   const { setActiveStudy, activeStudy } = useActiveStudy();
 
   // Set the active study if it doesn't match the current route
@@ -25,7 +25,7 @@ export default function StudyParticipantsPage() {
       breadcrumb={[
         { label: "Dashboard", href: "/dashboard" },
         { label: "Studies", href: "/studies" },
-        { label: activeStudy?.title || "Study", href: `/studies/${studyId}` },
+        { label: activeStudy?.title ?? "Study", href: `/studies/${studyId}` },
         { label: "Participants" },
       ]}
       createButton={{

src/app/(dashboard)/studies/[id]/trials/page.tsx

@@ -2,13 +2,13 @@
 
 import { useParams } from "next/navigation";
 import { Suspense, useEffect } from "react";
-import { ManagementPageLayout } from "~/components/ui/page-layout";
 import { TrialsTable } from "~/components/trials/TrialsTable";
+import { ManagementPageLayout } from "~/components/ui/page-layout";
 import { useActiveStudy } from "~/hooks/useActiveStudy";
 
 export default function StudyTrialsPage() {
   const params = useParams();
-  const studyId = params.id as string;
+  const studyId = typeof params.id === "string" ? params.id : "";
   const { setActiveStudy, activeStudy } = useActiveStudy();
 
   // Set the active study if it doesn't match the current route
@@ -25,7 +25,7 @@ export default function StudyTrialsPage() {
       breadcrumb={[
         { label: "Dashboard", href: "/dashboard" },
         { label: "Studies", href: "/studies" },
-        { label: activeStudy?.title || "Study", href: `/studies/${studyId}` },
+        { label: activeStudy?.title ?? "Study", href: `/studies/${studyId}` },
         { label: "Trials" },
       ]}
       createButton={{