chore: integrate firestore for particles (#32)

* plumb for firestore

* chore: cleanup orion api to only include essentials

* setup boilerplate for data and rendering

This includes zod types creation for API response validation, and
exploration of path based resolution of rendering particles.

* chore: structure container particles for rendering children

* wire firestore crud for particles

* integrate visibility to particles

* docs: explain particle view resolver

js/src/features/particles/folder-view.tsx

@@ -0,0 +1,20 @@
+import { Particle } from "@/api/types";
+import { useParticleChildren } from "@/hooks/use-particle-children";
+
+interface FolderViewProps {
+  folderParticle: Particle;
+  networkId: string;
+  particleSegments: string[];
+}
+
+export function FolderView({ networkId, particleSegments, folderParticle }: FolderViewProps) {
+  const { children, error, isLoading } = useParticleChildren(networkId, particleSegments);
+
+  return (
+    <div className="flex h-full items-center justify-center">
+      <p className="text-muted-foreground text-sm">
+        Folder view — {networkId}/{particleSegments.join("/")}
+      </p>
+    </div>
+  );
+}

js/src/features/particles/particle-list-view.tsx

@@ -0,0 +1,43 @@
+import { useParticleChildren } from "@/hooks/use-particle-children";
+
+interface ParticleListViewProps {
+  networkId: string;
+  particleSegments: string[];
+}
+
+/**
+ * Grid/list of child particles for a container (folder, stream root, or network root).
+ */
+export function ParticleListView({ networkId, particleSegments }: ParticleListViewProps) {
+  const { children, isLoading } = useParticleChildren(networkId, particleSegments);
+
+  if (isLoading) {
+    return (
+      <div className="flex h-full items-center justify-center">
+        <p className="text-muted-foreground text-sm">Loading particles...</p>
+      </div>
+    );
+  }
+
+  if (children.length === 0) {
+    return (
+      <div className="flex h-full items-center justify-center">
+        <p className="text-muted-foreground text-sm">No particles yet</p>
+      </div>
+    );
+  }
+
+  return (
+    <div className="grid grid-cols-2 gap-3 p-4">
+      {children.map((child) => (
+        <div
+          key={child.id}
+          className="rounded-lg border p-3 text-sm"
+        >
+          <p className="font-medium">{child.id}</p>
+          <p className="text-muted-foreground text-xs">{child.type}</p>
+        </div>
+      ))}
+    </div>
+  );
+}

js/src/features/particles/particle-view-resolver.tsx

@@ -0,0 +1,65 @@
+import { useParticle } from "@/hooks/use-particle";
+import { StreamView } from "./stream-view";
+import { FolderView } from "./folder-view";
+import { ParticleListView } from "./particle-list-view";
+import { isContainerType } from "@/api/types";
+
+interface ParticleViewResolverProps {
+  networkId: string;
+  particleSegments: string[];
+}
+
+/**
+ * Resolves a particle by its path segments and renders the appropriate view
+ * based on particle type (e.g. stream would show clips in story mode, folder would list files, etc.)
+ */
+export function ParticleViewResolver({ networkId, particleSegments }: ParticleViewResolverProps) {
+  const { particle, isLoading, error } = useParticle(networkId, particleSegments);
+
+  if (isLoading) {
+    return (
+      <div className="flex h-full items-center justify-center">
+        <p className="text-muted-foreground text-sm">Loading...</p>
+      </div>
+    );
+  }
+
+  if (error) {
+    return (
+      <div className="flex h-full items-center justify-center">
+        <p className="text-destructive text-sm">Failed to load particle</p>
+      </div>
+    );
+  }
+
+  // While the hook is stubbed, particle will be null — show a placeholder
+  if (!particle) {
+    return (
+      <div className="flex h-full items-center justify-center">
+        <p className="text-muted-foreground text-sm">
+          Particle: {particleSegments.join(" / ")}
+        </p>
+      </div>
+    );
+  }
+
+  switch (particle.type) {
+    case "stream":
+      return <StreamView streamParticle={particle} networkId={networkId} particleSegments={particleSegments} />;
+    case "folder":
+      return <FolderView folderParticle={particle} networkId={networkId} particleSegments={particleSegments} />;
+    default:
+      // For container types we haven't built a view for, fall back to list
+      if (isContainerType(particle.type)) {
+        return <ParticleListView networkId={networkId} particleSegments={particleSegments} />;
+      }
+      // Leaf particle — placeholder
+      return (
+        <div className="flex h-full items-center justify-center">
+          <p className="text-muted-foreground text-sm">
+            {particle.type} particle: {particle.id}
+          </p>
+        </div>
+      );
+  }
+}

js/src/features/particles/stream-view.tsx

@@ -0,0 +1,36 @@
+import { Particle } from "@/api/types";
+import { useParticleChildren } from "@/hooks/use-particle-children";
+
+interface StreamViewProps {
+  streamParticle: Particle;
+  networkId: string;
+  particleSegments: string[];
+}
+
+export function StreamView({ networkId, particleSegments, streamParticle }: StreamViewProps) {
+  const { children, error, isLoading } = useParticleChildren(networkId, particleSegments);
+
+  return (
+    <div className="flex h-full items-center justify-center">
+      <p className="text-muted-foreground text-sm">
+        Stream view — {networkId}/{particleSegments.join("/")}
+      </p>
+
+      {isLoading && <p className="text-muted-foreground text-sm">Loading stream data...</p>}
+      {error && <p className="text-destructive text-sm">Failed to load stream data</p>}
+
+      {!isLoading && !error && (
+        <div className="mt-4">
+          <p className="text-sm font-medium">Stream Children:</p>
+          <ul className="list-disc list-inside">
+            {children.map((child) => (
+              <li key={child.id} className="text-sm">
+                {child.id} ({child.type})
+              </li>
+            ))}
+          </ul>
+        </div>
+      )}
+    </div>
+  );
+}