Put a screen in front of it: projects, branches, a review you can watch

The app had an engine and no way to use it. This is the flow a person follows:
add a project, watch it clone, pick the branch to review and what to compare it
against, choose the rules and the model, describe what the change was for, and
watch the review run.

Five screens and a left rail. The rail carries a chip while a review is running,
because a review takes minutes and someone who navigates away needs a way back
to it. The review page opens on a snapshot read from the database and then
follows the event stream, so reloading mid-review shows the same run rather than
starting the story again.

Design decisions rather than defaults. Severity is the only place strong colour
appears, so a tool that coloured its own chrome would have nothing left to mean
"this one is critical". Numbers are tabular, because a review screen is mostly
numbers in columns. A running review pulses once for the whole page instead of
scattering spinners per widget, all of them out of step, and the pulse stops
entirely under prefers-reduced-motion. Empty states teach the next step rather
than apologising. Errors show what actually failed: a clone that fails prints
git's stderr verbatim.

The lint rules caught five effects calling setState synchronously. Fixing them
properly, with a cancellation guard per effect, also fixed a real bug:
navigating away during the first fetch would have set state on a component that
was already gone.

Driven end to end against a running production server before committing: added
a project from a local repository, watched the clone finish, listed its branches
with ahead and behind counts, imported the twelve-rule example protocol,
created a review pinned to the branch tips, and started it.

Author: Poolchaos

src/app/globals.css

@@ -1,28 +1,100 @@
 @import "tailwindcss";
 
 /*
- * Both themes are first-class (docs/04-UI-DESIGN.md). Tokens live here so
- * components never hardcode a colour; the full design system lands at WP-K.
+ * Both themes are first-class (docs/04-UI-DESIGN.md), so every colour is a
+ * token and no component hardcodes one.
+ *
+ * Severity is the only place strong colour appears. Everything else is a
+ * near-neutral surface with one restrained accent, because a reviewer's tool
+ * that colours its chrome leaves nothing left to mean "this one is critical".
  */
 @theme {
   --color-surface: oklch(99% 0.002 250);
   --color-surface-raised: oklch(97% 0.003 250);
+  --color-surface-sunken: oklch(95.5% 0.004 250);
   --color-border: oklch(90% 0.005 250);
+  --color-border-strong: oklch(82% 0.008 250);
   --color-ink: oklch(25% 0.01 250);
   --color-ink-muted: oklch(50% 0.01 250);
+  --color-ink-faint: oklch(64% 0.008 250);
+
+  --color-accent: oklch(52% 0.13 250);
+  --color-accent-ink: oklch(99% 0.002 250);
+  --color-accent-soft: oklch(94% 0.03 250);
+
+  --color-critical: oklch(52% 0.19 25);
+  --color-critical-soft: oklch(95% 0.04 25);
+  --color-warning: oklch(58% 0.13 75);
+  --color-warning-soft: oklch(95% 0.04 75);
+  --color-question: oklch(52% 0.11 250);
+  --color-question-soft: oklch(95% 0.03 250);
+  --color-good: oklch(52% 0.12 155);
+  --color-good-soft: oklch(95% 0.04 155);
+
+  --font-mono: ui-monospace, "SF Mono", "JetBrains Mono", "Fira Code", Menlo, Consolas, monospace;
 }
 
 @media (prefers-color-scheme: dark) {
   @theme {
     --color-surface: oklch(19% 0.008 250);
     --color-surface-raised: oklch(23% 0.009 250);
+    --color-surface-sunken: oklch(16% 0.007 250);
     --color-border: oklch(32% 0.01 250);
+    --color-border-strong: oklch(42% 0.012 250);
     --color-ink: oklch(94% 0.004 250);
     --color-ink-muted: oklch(70% 0.008 250);
+    --color-ink-faint: oklch(58% 0.008 250);
+
+    --color-accent: oklch(70% 0.12 250);
+    --color-accent-ink: oklch(17% 0.01 250);
+    --color-accent-soft: oklch(30% 0.05 250);
+
+    --color-critical: oklch(70% 0.16 25);
+    --color-critical-soft: oklch(28% 0.06 25);
+    --color-warning: oklch(76% 0.12 75);
+    --color-warning-soft: oklch(28% 0.05 75);
+    --color-question: oklch(72% 0.1 250);
+    --color-question-soft: oklch(27% 0.05 250);
+    --color-good: oklch(72% 0.11 155);
+    --color-good-soft: oklch(26% 0.05 155);
   }
 }
 
 body {
   background: var(--color-surface);
   color: var(--color-ink);
+  /* Counts, token totals and line numbers line up column-wise when they are
+     tabular, and a review screen is mostly numbers in columns. */
+  font-variant-numeric: tabular-nums;
+}
+
+/* A running review pulses rather than spinning. One steady signal for the
+   whole page beats a spinner per widget, all of them out of step. */
+@keyframes trysquare-pulse {
+  0%,
+  100% {
+    opacity: 1;
+  }
+  50% {
+    opacity: 0.45;
+  }
+}
+
+.pulse {
+  animation: trysquare-pulse 1.8s ease-in-out infinite;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .pulse {
+    animation: none;
+  }
+}
+
+::selection {
+  background: var(--color-accent-soft);
+}
+
+:focus-visible {
+  outline: 2px solid var(--color-accent);
+  outline-offset: 2px;
 }

src/app/layout.tsx

@@ -1,5 +1,6 @@
 import type { Metadata } from "next";
 import type { ReactNode } from "react";
+import { Rail } from "@/components/rail";
 import "./globals.css";
 
 export const metadata: Metadata = {
@@ -10,7 +11,12 @@ export const metadata: Metadata = {
 export default function RootLayout({ children }: { children: ReactNode }) {
   return (
     <html lang="en">
-      <body className="min-h-screen antialiased">{children}</body>
+      <body className="min-h-screen antialiased">
+        <div className="flex min-h-screen">
+          <Rail />
+          <main className="min-w-0 flex-1">{children}</main>
+        </div>
+      </body>
     </html>
   );
 }

src/app/page.tsx

@@ -1,14 +1,6 @@
+import { redirect } from "next/navigation";
+
 export default function HomePage() {
-  return (
-    <main className="mx-auto flex min-h-screen max-w-2xl flex-col justify-center gap-4 px-6">
-      <h1 className="text-2xl font-medium tracking-tight">Trysquare</h1>
-      <p className="text-[var(--color-ink-muted)]">
-        Scaffold only. No review functionality is implemented yet: the projects, ruleset, and review
-        surfaces arrive with WP-H and WP-I of the build plan.
-      </p>
-      <p className="text-sm text-[var(--color-ink-muted)]">
-        Progress is tracked in <code className="font-mono">docs/PROJECT-STATE.md</code>.
-      </p>
-    </main>
-  );
+  // Projects is where every flow starts, so the root is not a screen of its own.
+  redirect("/projects");
 }

src/app/projects/page.tsx

@@ -0,0 +1,166 @@
+"use client";
+
+/**
+ * Projects: what this app has cloned, and how to add another.
+ *
+ * A clone runs in the background, so the list polls while any project is still
+ * cloning and stops when none is. A failed clone shows git's own message,
+ * because "clone failed" tells nobody whether it was the address, the network
+ * or their SSH key.
+ */
+
+import Link from "next/link";
+import { useCallback, useEffect, useState } from "react";
+import { PageBody, PageHeader } from "@/components/page";
+import { Badge, Button, Card, Empty, Field, Input, Mono, Problem } from "@/components/ui";
+
+interface Project {
+  id: string;
+  name: string;
+  gitUrl: string;
+  defaultBranch: string;
+  cloneStatus: string;
+  cloneError: string | null;
+  lastFetchedAt: string | null;
+}
+
+export default function ProjectsPage() {
+  const [projects, setProjects] = useState<Project[] | null>(null);
+  const [gitUrl, setGitUrl] = useState("");
+  const [adding, setAdding] = useState(false);
+  const [error, setError] = useState("");
+
+  const load = useCallback(async () => {
+    const response = await fetch("/api/projects");
+    const body = (await response.json()) as { projects: Project[] };
+    setProjects(body.projects);
+    return body.projects;
+  }, []);
+
+  // Guarded against unmount rather than fired and forgotten: navigating away
+  // during the first fetch would otherwise set state on a gone component.
+  useEffect(() => {
+    let cancelled = false;
+    void (async () => {
+      const response = await fetch("/api/projects");
+      const body = (await response.json()) as { projects: Project[] };
+      if (!cancelled) setProjects(body.projects);
+    })();
+    return () => {
+      cancelled = true;
+    };
+  }, []);
+
+  // Polls only while something is actually cloning, so an idle screen is idle.
+  const cloning = projects?.some((project) => project.cloneStatus === "pending") ?? false;
+  useEffect(() => {
+    if (!cloning) return;
+    const timer = setInterval(() => void load(), 1000);
+    return () => clearInterval(timer);
+  }, [cloning, load]);
+
+  async function add(event: React.FormEvent) {
+    event.preventDefault();
+    setError("");
+    setAdding(true);
+    try {
+      const response = await fetch("/api/projects", {
+        method: "POST",
+        body: JSON.stringify({ gitUrl }),
+      });
+      const body = (await response.json()) as { error?: string };
+      if (!response.ok) {
+        setError(body.error ?? "The project could not be added.");
+        return;
+      }
+      setGitUrl("");
+      await load();
+    } finally {
+      setAdding(false);
+    }
+  }
+
+  return (
+    <>
+      <PageHeader title="Projects" subtitle="Cloned read-only. Nothing here is ever written to." />
+      <PageBody>
+        <Card className="mb-6 p-4">
+          <form onSubmit={add} className="flex flex-wrap items-end gap-3">
+            <div className="min-w-64 flex-1">
+              <Field
+                label="Add a project"
+                hint="Uses your machine's git credentials. This app stores no secrets."
+              >
+                <Input
+                  value={gitUrl}
+                  onChange={(event) => setGitUrl(event.target.value)}
+                  placeholder="git@github.com:you/your-app.git"
+                  spellCheck={false}
+                  autoComplete="off"
+                />
+              </Field>
+            </div>
+            <Button type="submit" variant="primary" disabled={adding || gitUrl.trim() === ""}>
+              {adding ? "Cloning..." : "Add project"}
+            </Button>
+          </form>
+          {error ? <div className="mt-3">{error ? <Problem>{error}</Problem> : null}</div> : null}
+        </Card>
+
+        {projects === null ? (
+          <p className="text-sm text-[var(--color-ink-muted)]">Loading...</p>
+        ) : projects.length === 0 ? (
+          <Empty title="No projects yet">
+            Add a repository above. Trysquare clones it read-only, then you pick two branches and
+            the rules to review them against.
+          </Empty>
+        ) : (
+          <ul className="grid gap-3">
+            {projects.map((project) => (
+              <li key={project.id}>
+                <Card className="p-4">
+                  <div className="flex flex-wrap items-start justify-between gap-3">
+                    <div className="min-w-0">
+                      <div className="flex items-center gap-2">
+                        {project.cloneStatus === "ready" ? (
+                          <Link
+                            href={`/projects/${project.id}`}
+                            className="font-medium hover:underline"
+                          >
+                            {project.name}
+                          </Link>
+                        ) : (
+                          <span className="font-medium">{project.name}</span>
+                        )}
+                        {project.cloneStatus === "pending" ? (
+                          <Badge tone="accent">cloning</Badge>
+                        ) : project.cloneStatus === "failed" ? (
+                          <Badge tone="critical">clone failed</Badge>
+                        ) : (
+                          <Badge tone="neutral">{project.defaultBranch}</Badge>
+                        )}
+                      </div>
+                      <Mono className="mt-1 block truncate text-xs text-[var(--color-ink-muted)]">
+                        {project.gitUrl}
+                      </Mono>
+                    </div>
+                    {project.cloneStatus === "ready" ? (
+                      <Link href={`/reviews/new?projectId=${project.id}`}>
+                        <Button variant="secondary">Review a branch</Button>
+                      </Link>
+                    ) : null}
+                  </div>
+                  {project.cloneError ? (
+                    <pre className="mt-3 overflow-x-auto rounded border border-[var(--color-critical)] bg-[var(--color-critical-soft)] p-3 text-xs text-[var(--color-critical)]">
+                      {project.cloneError}
+                    </pre>
+                  ) : null}
+                </Card>
+              </li>
+            ))}
+          </ul>
+        )}
+      </PageBody>
+    </>
+  );
+}