refactor(ui): full rewrite instance and code struct (#129)

## Summary by Sourcery

Refactor the UI to modernize effect handling, routing, and legacy APIs
while adding a reusable alert dialog component and cleaning up obsolete
stores.

New Features:
- Introduce a shared SaturnEffect context via ParticleBackground so
pages can access the effect without relying on global window APIs.
- Add a Base UI–powered alert dialog component for consistent
confirmation and warning flows across the app.
- Define a central router configuration module with instance routes to
standardize page wiring.

Bug Fixes:
- Ensure SaturnEffect nullish checks are handled safely when forwarding
pointer and touch events from the home view.

Enhancements:
- Rewrite ParticleBackground to manage its own SaturnEffect lifecycle
via React state and context instead of global accessors.
- Update the home view to use the SaturnEffect hook, simplify
pointer/touch handlers, and remove legacy game and release store usage.
- Refine layout and accessibility attributes for various form field and
label components, including field grouping and error rendering keys.
- Simplify sidebar navigation and adjust the user dropdown trigger to
work with the updated dropdown menu API.
- Wrap the root outlet for the home route with ParticleBackground only
on the index path to limit the effect to the intended view.
- Clean up imports and code style in radio group and other UI primitives
for consistency.

Chores:
- Remove deprecated UI stores and utility modules that are no longer
used with the new architecture.
- Add changeset entries documenting the Saturn effect refactor,
ParticleBackground rewrite, and removal of legacy store code.

3 files changed, 1227 insertions, 0 deletions

diff --git a/packages/ui/src/pages/instances/create.tsx b/packages/ui/src/pages/instances/create.tsx
new file mode 100644
index 0000000..57efea2
--- /dev/null
+++ b/packages/ui/src/pages/instances/create.tsx
@@ -0,0 +1,746 @@
+import { zodResolver } from "@hookform/resolvers/zod";
+import { defineStepper } from "@stepperize/react";
+import { open } from "@tauri-apps/plugin-shell";
+import { ArrowLeftIcon, Link2Icon, XIcon } from "lucide-react";
+import React, {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useState,
+} from "react";
+import {
+  Controller,
+  FormProvider,
+  useForm,
+  useFormContext,
+  Watch,
+} from "react-hook-form";
+import { useNavigate } from "react-router";
+import { toast } from "sonner";
+import z from "zod";
+import {
+  getFabricLoadersForVersion,
+  getForgeVersionsForGame,
+  getVersions,
+  installFabric,
+  installForge,
+  installVersion,
+  updateInstance,
+} from "@/client";
+import {
+  Accordion,
+  AccordionContent,
+  AccordionItem,
+  AccordionTrigger,
+} from "@/components/ui/accordion";
+import {
+  AlertDialog,
+  AlertDialogAction,
+  AlertDialogCancel,
+  AlertDialogContent,
+  AlertDialogDescription,
+  AlertDialogFooter,
+  AlertDialogHeader,
+  AlertDialogTitle,
+} from "@/components/ui/alert-dialog";
+import { Badge } from "@/components/ui/badge";
+import { Button } from "@/components/ui/button";
+import {
+  Field,
+  FieldContent,
+  FieldDescription,
+  FieldError,
+  FieldLabel,
+  FieldSet,
+  FieldTitle,
+} from "@/components/ui/field";
+import { Input } from "@/components/ui/input";
+import { RadioGroup, RadioGroupItem } from "@/components/ui/radio-group";
+import { ScrollArea } from "@/components/ui/scroll-area";
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from "@/components/ui/select";
+import { Separator } from "@/components/ui/separator";
+import { Spinner } from "@/components/ui/spinner";
+import { Textarea } from "@/components/ui/textarea";
+import { cn } from "@/lib/utils";
+import { useInstanceStore } from "@/models/instance";
+import type { FabricLoaderEntry, ForgeVersion, Version } from "@/types";
+
+const versionSchema = z.object({
+  versionId: z.string("Version is required"),
+});
+
+function VersionComponent() {
+  const {
+    control,
+    formState: { errors },
+  } = useFormContext<z.infer<typeof versionSchema>>();
+
+  const [versionSearch, setVersionSearch] = useState<string>("");
+  const [versionFilter, setVersionFilter] = useState<
+    "all" | "release" | "snapshot" | "old_alpha" | "old_beta" | null
+  >("release");
+
+  const [versions, setVersions] = useState<Version[] | null>(null);
+  const [isLoading, setIsLoading] = useState(false);
+  const [errorMessage, setErrorMessage] = useState<string | null>(null);
+  const loadVersions = useCallback(async () => {
+    setErrorMessage(null);
+    setIsLoading(true);
+    try {
+      const versions = await getVersions();
+      setVersions(versions);
+    } catch (e) {
+      console.error("Failed to load versions:", e);
+      setErrorMessage(`Failed to load versions: ${String(e)}`);
+      return;
+    } finally {
+      setIsLoading(false);
+    }
+  }, []);
+  useEffect(() => {
+    if (!versions) loadVersions();
+  }, [versions, loadVersions]);
+
+  const filteredVersions = useMemo(() => {
+    if (!versions) return null;
+    const all = versions;
+    let list = all.slice();
+    if (versionFilter !== "all") {
+      list = list.filter((v) => v.type === versionFilter);
+    }
+    if (versionSearch.trim()) {
+      const q = versionSearch.trim().toLowerCase().replace(/。/g, ".");
+      list = list.filter((v) => v.id.toLowerCase().includes(q));
+    }
+    return list;
+  }, [versions, versionFilter, versionSearch]);
+
+  return (
+    <div className="flex flex-col min-h-0 h-full overflow-hidden">
+      <div className="flex flex-row items-center mb-4 space-x-2">
+        <div className="flex flex-row space-x-2 w-full">
+          <FieldLabel className="text-nowrap">Versions</FieldLabel>
+          <Input
+            placeholder="Search versions..."
+            value={versionSearch}
+            onChange={(e) => setVersionSearch(e.target.value)}
+          />
+        </div>
+        <div className="flex flex-row space-x-2">
+          <FieldLabel className="text-nowrap">Type</FieldLabel>
+          <Select
+            value={versionFilter}
+            onValueChange={(value) => setVersionFilter(value)}
+          >
+            <SelectTrigger>
+              <SelectValue placeholder="Filter by type" />
+            </SelectTrigger>
+            <SelectContent alignItemWithTrigger={false}>
+              <SelectItem value="all">All Versions</SelectItem>
+              <SelectItem value="release">Release Versions</SelectItem>
+              <SelectItem value="snapshot">Snapshot Versions</SelectItem>
+              <SelectItem value="old_alpha">Old Alpha Versions</SelectItem>
+              <SelectItem value="old_beta">Old Beta Versions</SelectItem>
+            </SelectContent>
+          </Select>
+        </div>
+        <Button onClick={loadVersions} disabled={isLoading}>
+          Refresh
+        </Button>
+      </div>
+      {errorMessage && (
+        <div className="size-full flex flex-col items-center justify-center space-y-2">
+          <p className="text-red-500">{errorMessage}</p>
+          <Button variant="outline" onClick={loadVersions}>
+            Retry
+          </Button>
+        </div>
+      )}
+      {isLoading && !errorMessage ? (
+        <div className="size-full flex flex-col items-center justify-center">
+          <Spinner />
+          <p>Loading versions...</p>
+        </div>
+      ) : (
+        <div className="flex-1 overflow-hidden">
+          <ScrollArea className="size-full pr-2">
+            <Controller
+              name="versionId"
+              control={control}
+              render={({ field }) => (
+                <RadioGroup
+                  {...field}
+                  value={field.value || ""}
+                  className="space-y-2"
+                >
+                  {filteredVersions?.map((version) => (
+                    <FieldLabel key={version.id} htmlFor={version.id}>
+                      <Field orientation="horizontal" className="py-2">
+                        <FieldContent>
+                          <FieldTitle>
+                            {version.id}
+                            <Badge variant="outline">{version.type}</Badge>
+                          </FieldTitle>
+                          <FieldDescription>
+                            {new Date(version.releaseTime).toLocaleString()}
+                          </FieldDescription>
+                        </FieldContent>
+                        <div className="flex flex-row space-x-2 items-center">
+                          <Button
+                            size="icon"
+                            variant="ghost"
+                            onClick={() => {
+                              open(
+                                `https://zh.minecraft.wiki/w/Java%E7%89%88${version.id}`,
+                              );
+                            }}
+                          >
+                            <Link2Icon />
+                          </Button>
+                          <RadioGroupItem value={version.id} id={version.id} />
+                        </div>
+                      </Field>
+                    </FieldLabel>
+                  ))}
+                </RadioGroup>
+              )}
+            ></Controller>
+          </ScrollArea>
+        </div>
+      )}
+      {errors.versionId && <FieldError errors={[errors.versionId]} />}
+    </div>
+  );
+}
+
+const instanceSchema = z.object({
+  name: z.string().min(1, "Instance name is required"),
+  notes: z.string().max(100, "Notes must be at most 100 characters").optional(),
+  modLoader: z.enum(["fabric", "forge"]).optional(),
+  modLoaderVersion: z.string().optional(),
+});
+
+function InstanceComponent() {
+  const {
+    control,
+    register,
+    formState: { errors },
+  } = useFormContext<z.infer<typeof instanceSchema>>();
+
+  const versionId = useVersionId();
+
+  const [forgeVersions, setForgeVersions] = useState<ForgeVersion[] | null>(
+    null,
+  );
+  const [fabricVersions, setFabricVersions] = useState<
+    FabricLoaderEntry[] | null
+  >(null);
+
+  const [isLoadingForge, setIsLoadingForge] = useState(false);
+  const [isLoadingFabric, setIsLoadingFabric] = useState(false);
+  const loadForgeVersions = useCallback(async () => {
+    if (forgeVersions) return;
+    if (!versionId) return toast.error("Version ID is not set");
+    setIsLoadingForge(true);
+    try {
+      const versions = await getForgeVersionsForGame(versionId);
+      setForgeVersions(versions);
+    } catch (e) {
+      console.error("Failed to load Forge versions:", e);
+      toast.error(`Failed to load Forge versions: ${String(e)}`);
+    } finally {
+      setIsLoadingForge(false);
+    }
+  }, [versionId, forgeVersions]);
+  const loadFabricVersions = useCallback(async () => {
+    if (fabricVersions) return;
+    if (!versionId) return toast.error("Version ID is not set");
+    setIsLoadingFabric(true);
+    try {
+      const versions = await getFabricLoadersForVersion(versionId);
+      setFabricVersions(versions);
+    } catch (e) {
+      console.error("Failed to load Fabric versions:", e);
+      toast.error(`Failed to load Fabric versions: ${String(e)}`);
+    } finally {
+      setIsLoadingFabric(false);
+    }
+  }, [versionId, fabricVersions]);
+
+  const modLoaderField = register("modLoader");
+  const modLoaderVersionField = register("modLoaderVersion");
+
+  return (
+    <ScrollArea className="size-full pr-2">
+      <div className="h-full flex flex-col space-y-4">
+        <div className="bg-card w-full p-6 shadow shrink-0">
+          <FieldSet className="w-full">
+            <Field orientation="horizontal">
+              <FieldLabel htmlFor="name" className="text-nowrap" required>
+                Instance Name
+              </FieldLabel>
+              <Input {...register("name")} aria-invalid={!!errors.name} />
+              {errors.name && <FieldError errors={[errors.name]} />}
+            </Field>
+            <Field>
+              <FieldLabel htmlFor="notes" className="text-nowrap">
+                Instance Notes
+              </FieldLabel>
+              <Textarea
+                className="resize-none min-h-0"
+                {...register("notes")}
+                rows={1}
+              />
+              {errors.notes && <FieldError errors={[errors.notes]} />}
+            </Field>
+          </FieldSet>
+        </div>
+
+        <Accordion className="border">
+          <AccordionItem
+            value="forge"
+            onOpenChange={(open) => {
+              if (open) loadForgeVersions();
+            }}
+          >
+            <Watch
+              control={control}
+              render={({ modLoader, modLoaderVersion }) => (
+                <AccordionTrigger
+                  className="border-b px-4 py-3"
+                  disabled={modLoader && modLoader !== "forge"}
+                >
+                  <div className="flex flex-row w-full items-center space-x-4">
+                    <span className="font-bold">Forge</span>
+                    {modLoader === "forge" && (
+                      <>
+                        <span className="text-nowrap font-bold">
+                          {modLoaderVersion}
+                        </span>
+                        <Button
+                          size="icon"
+                          variant="ghost"
+                          nativeButton={false}
+                          onClick={(e) => {
+                            e.stopPropagation();
+                            modLoaderField.onChange({
+                              target: {
+                                name: modLoaderField.name,
+                                value: null,
+                              },
+                            });
+                            modLoaderVersionField.onChange({
+                              target: {
+                                name: modLoaderVersionField.name,
+                                value: null,
+                              },
+                            });
+                          }}
+                          render={(domProps) => (
+                            <div {...domProps}>
+                              <XIcon />
+                            </div>
+                          )}
+                        />
+                      </>
+                    )}
+                  </div>
+                </AccordionTrigger>
+              )}
+            />
+            <AccordionContent>
+              {isLoadingForge ? (
+                <div className="h-full flex flex-col items-center justify-center">
+                  <Spinner />
+                  <p>Loading Forge versions...</p>
+                </div>
+              ) : (
+                <div className="h-full flex flex-col">
+                  {forgeVersions?.map((version, idx) => (
+                    <React.Fragment
+                      key={`forge-${version.version}-${version.minecraftVersion}`}
+                    >
+                      <Button
+                        variant="ghost"
+                        className="p-3 py-6 border-b justify-start"
+                        onClick={() => {
+                          modLoaderField.onChange({
+                            target: {
+                              name: modLoaderField.name,
+                              value: "forge",
+                            },
+                          });
+                          modLoaderVersionField.onChange({
+                            target: {
+                              name: modLoaderVersionField.name,
+                              value: version.version,
+                            },
+                          });
+                        }}
+                      >
+                        Forge {version.version} for Minecraft{" "}
+                        {version.minecraftVersion}
+                      </Button>
+                      {idx !== forgeVersions.length - 1 && <Separator />}
+                    </React.Fragment>
+                  ))}
+                </div>
+              )}
+            </AccordionContent>
+          </AccordionItem>
+          <AccordionItem
+            value="fabric"
+            onOpenChange={(open) => {
+              if (open) loadFabricVersions();
+            }}
+          >
+            <Watch
+              control={control}
+              render={({ modLoader, modLoaderVersion }) => (
+                <AccordionTrigger
+                  className="border-b px-4 py-3"
+                  disabled={modLoader && modLoader !== "fabric"}
+                >
+                  <div className="flex flex-row w-full items-center space-x-4">
+                    <span className="font-bold">Fabric</span>
+                    {modLoader === "fabric" && (
+                      <>
+                        <span className="text-nowrap font-bold">
+                          {modLoaderVersion}
+                        </span>
+                        <Button
+                          size="icon"
+                          variant="ghost"
+                          nativeButton={false}
+                          onClick={(e) => {
+                            e.stopPropagation();
+                            modLoaderField.onChange({
+                              target: {
+                                name: modLoaderField.name,
+                                value: null,
+                              },
+                            });
+                            modLoaderVersionField.onChange({
+                              target: {
+                                name: modLoaderVersionField.name,
+                                value: null,
+                              },
+                            });
+                          }}
+                          render={(domProps) => (
+                            <div {...domProps}>
+                              <XIcon />
+                            </div>
+                          )}
+                        />
+                      </>
+                    )}
+                  </div>
+                </AccordionTrigger>
+              )}
+            />
+
+            <AccordionContent>
+              {isLoadingFabric ? (
+                <div className="h-full flex flex-col items-center justify-center">
+                  <Spinner />
+                  <p>Loading Fabric versions...</p>
+                </div>
+              ) : (
+                <div className="h-full flex flex-col">
+                  {fabricVersions?.map((version, idx) => (
+                    <React.Fragment
+                      key={`fabric-${version.loader.version}-${version.intermediary.version}`}
+                    >
+                      <Button
+                        variant="ghost"
+                        className="p-3 py-6 border-b justify-start"
+                        onClick={() => {
+                          modLoaderField.onChange({
+                            target: {
+                              name: modLoaderField.name,
+                              value: "fabric",
+                            },
+                          });
+                          modLoaderVersionField.onChange({
+                            target: {
+                              name: modLoaderVersionField.name,
+                              value: version.loader.version,
+                            },
+                          });
+                        }}
+                      >
+                        Fabric {version.loader.version} for Minecraft{" "}
+                        {version.intermediary.version}
+                      </Button>
+                      {idx !== fabricVersions.length - 1 && <Separator />}
+                    </React.Fragment>
+                  ))}
+                </div>
+              )}
+            </AccordionContent>
+          </AccordionItem>
+        </Accordion>
+      </div>
+    </ScrollArea>
+  );
+}
+
+const VersionIdContext = createContext<string | null>(null);
+export const useVersionId = () => useContext(VersionIdContext);
+
+const { useStepper, Stepper } = defineStepper(
+  {
+    id: "version",
+    title: "Version",
+    Component: VersionComponent,
+    schema: versionSchema,
+  },
+  {
+    id: "instance",
+    title: "Instance",
+    Component: InstanceComponent,
+    schema: instanceSchema,
+  },
+);
+
+export function CreateInstancePage() {
+  const stepper = useStepper();
+  const schema = stepper.state.current.data.schema;
+  const form = useForm<z.infer<typeof schema>>({
+    resolver: zodResolver(schema),
+  });
+  const navigate = useNavigate();
+
+  const instanceStore = useInstanceStore();
+
+  const [versions, setVersions] = useState<Version[] | null>(null);
+  useEffect(() => {
+    const loadVersions = async () => {
+      const versions = await getVersions();
+      setVersions(versions);
+    };
+    if (!versions) loadVersions();
+  }, [versions]);
+
+  // Step 2
+  const [versionId, setVersionId] = useState<string | null>(null);
+
+  // Step 2
+  // 这里不要动，后面会做一个download页面，需要迁移到download-models
+  const [_instanceMeta, setInstanceMeta] = useState<z.infer<
+    typeof instanceSchema
+  > | null>(null);
+
+  const [isCreating, setIsCreating] = useState(false);
+  const handleSubmit = useCallback(
+    async (data: z.infer<typeof schema>) => {
+      switch (stepper.state.current.data.id) {
+        case "version":
+          setVersionId((data as z.infer<typeof versionSchema>).versionId);
+          return await stepper.navigation.next();
+        case "instance":
+          setInstanceMeta(data as z.infer<typeof instanceSchema>);
+      }
+
+      if (!versionId) return toast.error("Please select a version first");
+
+      setIsCreating(true);
+
+      // 这里不要动，React数据是异步更新，直接用的数据才是实时的
+      const instanceMeta = data as z.infer<typeof instanceSchema>;
+
+      try {
+        const instance = await instanceStore.create(instanceMeta.name);
+        instance.notes = instanceMeta.notes ?? null;
+        await updateInstance(instance);
+
+        await installVersion(instance.id, versionId);
+        switch (instanceMeta.modLoader) {
+          case "fabric":
+            if (!instanceMeta.modLoaderVersion) {
+              toast.error("Please select a Fabric loader version");
+              return;
+            }
+            await installFabric(
+              instance.id,
+              versionId,
+              instanceMeta.modLoaderVersion,
+            );
+            break;
+          case "forge":
+            if (!instanceMeta.modLoaderVersion) {
+              toast.error("Please select a Forge loader version");
+              return;
+            }
+            await installForge(
+              instance.id,
+              versionId,
+              instanceMeta.modLoaderVersion,
+            );
+            break;
+          default:
+            toast.error("Unsupported mod loader");
+            break;
+        }
+
+        navigate("/instances");
+      } catch (error) {
+        console.error(error);
+        toast.error("Failed to create instance");
+      } finally {
+        setIsCreating(false);
+      }
+    },
+    [stepper, instanceStore.create, versionId, navigate],
+  );
+
+  return (
+    <FormProvider {...form}>
+      <Stepper.List className="w-full flex list-none flex-row items-center justify-center px-6 mb-6">
+        {stepper.state.all.map((step, idx) => {
+          const current = stepper.state.current;
+          const isInactive = stepper.state.current.data.id !== step.id;
+          const isLast = stepper.lookup.getLast().id === step.id;
+          return (
+            <React.Fragment key={`stepper-item-${step.id}`}>
+              <Stepper.Item step={step.id}>
+                <Stepper.Trigger
+                  render={(domProps) => (
+                    <Button
+                      className="rounded-full"
+                      variant={isInactive ? "secondary" : "default"}
+                      size="icon"
+                      disabled={isInactive}
+                      {...domProps}
+                    >
+                      <Stepper.Indicator>{idx + 1}</Stepper.Indicator>
+                    </Button>
+                  )}
+                />
+              </Stepper.Item>
+              {!isLast && (
+                <Stepper.Separator
+                  orientation="horizontal"
+                  data-status={current.status}
+                  className={cn(
+                    "w-full h-0.5 mx-2",
+                    "bg-muted data-[status=success]:bg-primary data-disabled:opacity-50",
+                    "transition-all duration-300 ease-in-out",
+                  )}
+                />
+              )}
+            </React.Fragment>
+          );
+        })}
+      </Stepper.List>
+      <form
+        className="flex flex-col flex-1 min-h-0 space-y-4 px-6"
+        onSubmit={form.handleSubmit(handleSubmit)}
+      >
+        <div className="flex-1 overflow-hidden w-full max-w-xl mx-auto">
+          <VersionIdContext.Provider value={versionId}>
+            {stepper.flow.switch({
+              version: ({ Component }) => <Component />,
+              instance: ({ Component }) => <Component />,
+            })}
+          </VersionIdContext.Provider>
+        </div>
+        <div className="w-full flex flex-row justify-between">
+          <Stepper.Prev
+            render={(domProps) => (
+              <Button
+                type="button"
+                variant="secondary"
+                disabled={isCreating}
+                {...domProps}
+              >
+                Previous
+              </Button>
+            )}
+          />
+          {stepper.state.isLast ? (
+            <Button type="submit" disabled={isCreating}>
+              {isCreating ? (
+                <>
+                  <Spinner />
+                  Creating
+                </>
+              ) : (
+                "Create"
+              )}
+            </Button>
+          ) : (
+            <Button type="submit">Next</Button>
+          )}
+        </div>
+      </form>
+    </FormProvider>
+  );
+}
+
+function PageWrapper() {
+  const navigate = useNavigate();
+  const [showCancelDialog, setShowCancelDialog] = useState(false);
+
+  return (
+    <div className="flex size-full overflow-hidden px-6 py-8">
+      <Stepper.Root
+        className="flex flex-col flex-1 space-y-4"
+        orientation="horizontal"
+      >
+        {({ stepper }) => (
+          <>
+            <div className="flex flex-row space-x-4">
+              <Button
+                variant="secondary"
+                size="icon"
+                onClick={() => {
+                  if (stepper.state.isFirst) return navigate(-1);
+                  setShowCancelDialog(true);
+                }}
+              >
+                <ArrowLeftIcon />
+              </Button>
+              <h1 className="text-2xl font-bold">Create Instance</h1>
+            </div>
+            <p className="text-sm text-muted-foreground">
+              Create a new Minecraft instance.
+            </p>
+            <CreateInstancePage />
+          </>
+        )}
+      </Stepper.Root>
+
+      <AlertDialog open={showCancelDialog} onOpenChange={setShowCancelDialog}>
+        <AlertDialogContent>
+          <AlertDialogHeader>
+            <AlertDialogTitle>Are you absolutely sure?</AlertDialogTitle>
+            <AlertDialogDescription>
+              All your progress will be lost.
+            </AlertDialogDescription>
+          </AlertDialogHeader>
+          <AlertDialogFooter>
+            <AlertDialogCancel>Cancel</AlertDialogCancel>
+            <AlertDialogAction
+              variant="destructive"
+              onClick={() => navigate(-1)}
+            >
+              Continue
+            </AlertDialogAction>
+          </AlertDialogFooter>
+        </AlertDialogContent>
+      </AlertDialog>
+    </div>
+  );
+}
+
+export default PageWrapper;
diff --git a/packages/ui/src/pages/instances/index.tsx b/packages/ui/src/pages/instances/index.tsx
new file mode 100644
index 0000000..e6cd734
--- /dev/null
+++ b/packages/ui/src/pages/instances/index.tsx
@@ -0,0 +1,462 @@
+import { open, save } from "@tauri-apps/plugin-dialog";
+import {
+  CopyIcon,
+  EditIcon,
+  EllipsisIcon,
+  FolderOpenIcon,
+  Plus,
+  RocketIcon,
+  Trash2Icon,
+  XIcon,
+} from "lucide-react";
+import { useEffect, useState } from "react";
+import { useNavigate } from "react-router";
+import { toast } from "sonner";
+import { openFileExplorer } from "@/client";
+import InstanceEditorModal from "@/components/instance-editor-modal";
+import { Button } from "@/components/ui/button";
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+} from "@/components/ui/dialog";
+import { Input } from "@/components/ui/input";
+import { cn } from "@/lib/utils";
+import { useAuthStore } from "@/models/auth";
+import { useGameStore } from "@/models/game";
+import { useInstanceStore } from "@/models/instance";
+import type { Instance } from "@/types";
+
+export function InstancesPage() {
+  const instancesStore = useInstanceStore();
+  const navigate = useNavigate();
+
+  const account = useAuthStore((state) => state.account);
+  const {
+    startGame,
+    runningInstanceId,
+    stoppingInstanceId,
+    launchingInstanceId,
+    stopGame,
+  } = useGameStore();
+
+  const [showEditModal, setShowEditModal] = useState(false);
+  const [showDeleteConfirm, setShowDeleteConfirm] = useState(false);
+  const [showDuplicateModal, setShowDuplicateModal] = useState(false);
+
+  const [isImporting, setIsImporting] = useState(false);
+  const [repairing, setRepairing] = useState(false);
+  const [exportingId, setExportingId] = useState<string | null>(null);
+
+  // Selected / editing instance state
+  const [selectedInstance, setSelectedInstance] = useState<Instance | null>(
+    null,
+  );
+  const [editingInstance, setEditingInstance] = useState<Instance | null>(null);
+
+  // Form fields
+  const [duplicateName, setDuplicateName] = useState("");
+
+  useEffect(() => {
+    instancesStore.refresh();
+  }, [instancesStore.refresh]);
+
+  // Handlers to open modals
+  const openCreate = () => {
+    navigate("/instances/create");
+  };
+
+  const openEdit = (instance: Instance) => {
+    setEditingInstance({ ...instance });
+    setShowEditModal(true);
+  };
+
+  const openDelete = (instance: Instance) => {
+    setSelectedInstance(instance);
+    setShowDeleteConfirm(true);
+  };
+
+  const openDuplicate = (instance: Instance) => {
+    setSelectedInstance(instance);
+    setDuplicateName(`${instance.name} (Copy)`);
+    setShowDuplicateModal(true);
+  };
+
+  const confirmDelete = async () => {
+    if (!selectedInstance) return;
+    await instancesStore.delete(selectedInstance.id);
+    setSelectedInstance(null);
+    setShowDeleteConfirm(false);
+  };
+
+  const confirmDuplicate = async () => {
+    if (!selectedInstance) return;
+    const name = duplicateName.trim();
+    if (!name) return;
+    await instancesStore.duplicate(selectedInstance.id, name);
+    setSelectedInstance(null);
+    setDuplicateName("");
+    setShowDuplicateModal(false);
+  };
+
+  const handleImport = async () => {
+    setIsImporting(true);
+    try {
+      const selected = await open({
+        multiple: false,
+        filters: [{ name: "Zip Archive", extensions: ["zip"] }],
+      });
+
+      if (typeof selected !== "string") {
+        return;
+      }
+
+      await instancesStore.importArchive(selected);
+    } finally {
+      setIsImporting(false);
+    }
+  };
+
+  const handleRepair = async () => {
+    setRepairing(true);
+    try {
+      await instancesStore.repair();
+    } finally {
+      setRepairing(false);
+    }
+  };
+
+  const handleExport = async (instance: Instance) => {
+    setExportingId(instance.id);
+    try {
+      const filePath = await save({
+        defaultPath: `${instance.name.replace(/[\\/:*?"<>|]/g, "_")}.zip`,
+        filters: [{ name: "Zip Archive", extensions: ["zip"] }],
+      });
+
+      if (!filePath) {
+        return;
+      }
+
+      await instancesStore.exportArchive(instance.id, filePath);
+    } finally {
+      setExportingId(null);
+    }
+  };
+
+  return (
+    <div className="h-full flex flex-col gap-4 p-6 overflow-y-auto">
+      <div className="flex items-center justify-between">
+        <h1 className="text-2xl font-bold text-gray-900 dark:text-white">
+          Instances
+        </h1>
+        <div className="flex flex-row space-x-2">
+          <Button
+            type="button"
+            variant="outline"
+            onClick={handleImport}
+            disabled={isImporting}
+          >
+            {isImporting ? "Importing..." : "Import"}
+          </Button>
+          <Button
+            type="button"
+            variant="outline"
+            onClick={handleRepair}
+            disabled={repairing}
+          >
+            {repairing ? "Repairing..." : "Repair Index"}
+          </Button>
+          <Button
+            type="button"
+            onClick={openCreate}
+            className="px-4 py-2 transition-colors"
+          >
+            <Plus size={18} />
+            Create Instance
+          </Button>
+        </div>
+      </div>
+
+      {instancesStore.instances.length === 0 ? (
+        <div className="flex-1 flex items-center justify-center">
+          <div className="text-center text-gray-500 dark:text-gray-400">
+            <p className="text-lg mb-2">No instances yet</p>
+            <p className="text-sm">Create your first instance to get started</p>
+          </div>
+        </div>
+      ) : (
+        <ul className="flex flex-col space-y-3">
+          {instancesStore.instances.map((instance) => {
+            const isActive = instancesStore.activeInstance?.id === instance.id;
+            const isLaunching = launchingInstanceId === instance.id;
+            const isStopping = stoppingInstanceId === instance.id;
+            const isRunning = runningInstanceId === instance.id;
+
+            return (
+              <li
+                key={instance.id}
+                onClick={() => instancesStore.setActiveInstance(instance)}
+                onKeyDown={async (e) => {
+                  if (e.key === "Enter") {
+                    try {
+                      await instancesStore.setActiveInstance(instance);
+                    } catch (e) {
+                      console.error("Failed to set active instance:", e);
+                      toast.error("Error setting active instance");
+                    }
+                  }
+                }}
+                className="cursor-pointer"
+              >
+                <div
+                  className={cn(
+                    "flex flex-row space-x-3 p-3 justify-between",
+                    "border bg-card/5 backdrop-blur-xl",
+                    "hover:bg-accent/50 transition-colors",
+                    isActive && "border-primary",
+                  )}
+                >
+                  <div className="flex flex-row space-x-4">
+                    {instance.iconPath ? (
+                      <div className="w-12 h-12 rounded overflow-hidden">
+                        <img
+                          src={instance.iconPath}
+                          alt={instance.name}
+                          className="w-full h-full object-cover"
+                        />
+                      </div>
+                    ) : (
+                      <div className="w-12 h-12 rounded bg-linear-to-br from-blue-500 to-purple-600 flex items-center justify-center">
+                        <span className="text-white font-bold text-lg">
+                          {instance.name.charAt(0).toUpperCase()}
+                        </span>
+                      </div>
+                    )}
+
+                    <div className="flex flex-col">
+                      <h3 className="text-lg font-semibold">{instance.name}</h3>
+                      {instance.versionId ? (
+                        <p className="text-sm text-muted-foreground">
+                          {instance.versionId}
+                        </p>
+                      ) : (
+                        <p className="text-sm text-muted-foreground">
+                          No version selected
+                        </p>
+                      )}
+                    </div>
+                  </div>
+
+                  <div className="flex items-center">
+                    <div className="flex flex-row space-x-2">
+                      <Button
+                        variant={isRunning ? "destructive" : "ghost"}
+                        size="icon"
+                        onClick={async (e) => {
+                          e.stopPropagation();
+
+                          try {
+                            await instancesStore.setActiveInstance(instance);
+                          } catch (error) {
+                            console.error(
+                              "Failed to set active instance:",
+                              error,
+                            );
+                            toast.error("Error setting active instance");
+                            return;
+                          }
+
+                          if (isRunning) {
+                            await stopGame(instance.id);
+                            return;
+                          }
+
+                          if (!instance.versionId) {
+                            toast.error("No version selected or installed");
+                            return;
+                          }
+
+                          if (!account) {
+                            toast.info("Please login first");
+                            return;
+                          }
+
+                          try {
+                            await startGame(instance.id, instance.versionId);
+                          } catch (error) {
+                            console.error("Failed to start game:", error);
+                            toast.error("Error starting game");
+                          }
+                        }}
+                        disabled={
+                          (!!runningInstanceId &&
+                            runningInstanceId !== instance.id) ||
+                          isLaunching ||
+                          isStopping
+                        }
+                      >
+                        {isLaunching || isStopping ? (
+                          <EllipsisIcon />
+                        ) : isRunning ? (
+                          <XIcon />
+                        ) : (
+                          <RocketIcon />
+                        )}
+                      </Button>
+                      <Button
+                        variant="ghost"
+                        size="icon"
+                        onClick={(e) => {
+                          e.stopPropagation();
+                          void openFileExplorer(instance.gameDir);
+                        }}
+                      >
+                        <FolderOpenIcon />
+                      </Button>
+                      <Button
+                        variant="ghost"
+                        size="icon"
+                        onClick={(e) => {
+                          e.stopPropagation();
+                          void handleExport(instance);
+                        }}
+                        disabled={exportingId === instance.id}
+                      >
+                        <span className="text-xs">
+                          {exportingId === instance.id ? "..." : "ZIP"}
+                        </span>
+                      </Button>
+                      <Button
+                        variant="ghost"
+                        size="icon"
+                        onClick={(e) => {
+                          e.stopPropagation();
+                          openDuplicate(instance);
+                        }}
+                      >
+                        <CopyIcon />
+                      </Button>
+                      <Button
+                        variant="ghost"
+                        size="icon"
+                        onClick={(e) => {
+                          e.stopPropagation();
+                          openEdit(instance);
+                        }}
+                      >
+                        <EditIcon />
+                      </Button>
+                      <Button
+                        variant="destructive"
+                        size="icon"
+                        onClick={(e) => {
+                          e.stopPropagation();
+                          openDelete(instance);
+                        }}
+                      >
+                        <Trash2Icon />
+                      </Button>
+                    </div>
+                  </div>
+                </div>
+              </li>
+            );
+          })}
+        </ul>
+      )}
+
+      {/*<InstanceCreationModal
+        open={showCreateModal}
+        onOpenChange={setShowCreateModal}
+      />*/}
+
+      <InstanceEditorModal
+        open={showEditModal}
+        instance={editingInstance}
+        onOpenChange={(open) => {
+          setShowEditModal(open);
+          if (!open) setEditingInstance(null);
+        }}
+      />
+
+      {/* Delete Confirmation */}
+      <Dialog open={showDeleteConfirm} onOpenChange={setShowDeleteConfirm}>
+        <DialogContent>
+          <DialogHeader>
+            <DialogTitle>Delete Instance</DialogTitle>
+            <DialogDescription>
+              Are you sure you want to delete "{selectedInstance?.name}"? This
+              action cannot be undone.
+            </DialogDescription>
+          </DialogHeader>
+
+          <DialogFooter>
+            <Button
+              type="button"
+              variant="outline"
+              onClick={() => {
+                setShowDeleteConfirm(false);
+                setSelectedInstance(null);
+              }}
+            >
+              Cancel
+            </Button>
+            <Button
+              type="button"
+              onClick={confirmDelete}
+              className="bg-red-600 text-white hover:bg-red-500"
+            >
+              Delete
+            </Button>
+          </DialogFooter>
+        </DialogContent>
+      </Dialog>
+
+      {/* Duplicate Modal */}
+      <Dialog open={showDuplicateModal} onOpenChange={setShowDuplicateModal}>
+        <DialogContent>
+          <DialogHeader>
+            <DialogTitle>Duplicate Instance</DialogTitle>
+            <DialogDescription>
+              Provide a name for the duplicated instance.
+            </DialogDescription>
+          </DialogHeader>
+
+          <div className="mt-4">
+            <Input
+              value={duplicateName}
+              onChange={(e) => setDuplicateName(e.target.value)}
+              placeholder="New instance name"
+              onKeyDown={(e) => e.key === "Enter" && confirmDuplicate()}
+            />
+          </div>
+
+          <DialogFooter>
+            <Button
+              type="button"
+              variant="outline"
+              onClick={() => {
+                setShowDuplicateModal(false);
+                setSelectedInstance(null);
+                setDuplicateName("");
+              }}
+            >
+              Cancel
+            </Button>
+            <Button
+              type="button"
+              onClick={confirmDuplicate}
+              disabled={!duplicateName.trim()}
+            >
+              Duplicate
+            </Button>
+          </DialogFooter>
+        </DialogContent>
+      </Dialog>
+    </div>
+  );
+}
diff --git a/packages/ui/src/pages/instances/routes.ts b/packages/ui/src/pages/instances/routes.ts
new file mode 100644
index 0000000..cd1255d
--- /dev/null
+++ b/packages/ui/src/pages/instances/routes.ts
@@ -0,0 +1,19 @@
+import type { RouteObject } from "react-router";
+import CreateInstancePage from "./create";
+import { InstancesPage } from "./index";
+
+const routes = {
+  path: "/instances",
+  children: [
+    {
+      index: true,
+      Component: InstancesPage,
+    },
+    {
+      path: "create",
+      Component: CreateInstancePage,
+    },
+  ],
+} satisfies RouteObject;
+
+export default routes;