stage 8-complete

app/admin/projects/[id]/assemblies/[assemblyId]/AssemblyDetailClient.tsx

@@ -39,6 +39,7 @@ interface PartRow {
   hasStep: boolean;
   hasDrawing: boolean;
   hasCut: boolean;
+  thumbnailFileId: string | null;
   operationCount: number;
 }
 
@@ -100,6 +101,7 @@ export default function AssemblyDetailClient({
         <table className="w-full text-sm">
           <thead className="bg-slate-50 text-left text-slate-600 border-b border-slate-200">
             <tr>
+              <th className="px-4 py-2 font-medium w-[90px]">Preview</th>
               <th className="px-4 py-2 font-medium">Code</th>
               <th className="px-4 py-2 font-medium">Name</th>
               <th className="px-4 py-2 font-medium">Material</th>
@@ -112,6 +114,26 @@ export default function AssemblyDetailClient({
           <tbody>
             {parts.map((p) => (
               <tr key={p.id} className="border-b border-slate-100 last:border-0">
+                <td className="px-4 py-3">
+                  {p.thumbnailFileId ? (
+                    // eslint-disable-next-line @next/next/no-img-element
+                    <img
+                      src={`/api/v1/files/${p.thumbnailFileId}/download`}
+                      alt={`${p.code} preview`}
+                      width={72}
+                      height={54}
+                      className="rounded border border-slate-200 bg-slate-50 object-cover w-[72px] h-[54px]"
+                    />
+                  ) : p.hasStep ? (
+                    <div className="rounded border border-dashed border-slate-300 bg-slate-50 w-[72px] h-[54px] flex items-center justify-center text-[10px] text-slate-400">
+                      open to render
+                    </div>
+                  ) : (
+                    <div className="rounded border border-slate-200 bg-slate-50 w-[72px] h-[54px] flex items-center justify-center text-[10px] text-slate-400">
+                      no STEP
+                    </div>
+                  )}
+                </td>
                 <td className="px-4 py-3 font-mono text-slate-700">{p.code}</td>
                 <td className="px-4 py-3 font-medium">{p.name}</td>
                 <td className="px-4 py-3 text-slate-600">{p.material ?? "—"}</td>
@@ -136,7 +158,7 @@ export default function AssemblyDetailClient({
             ))}
             {parts.length === 0 && (
               <tr>
-                <td colSpan={7} className="px-4 py-10 text-center text-slate-500">
+                <td colSpan={8} className="px-4 py-10 text-center text-slate-500">
                   No parts yet.
                 </td>
               </tr>

app/admin/projects/[id]/assemblies/[assemblyId]/page.tsx

@@ -21,6 +21,7 @@ export default async function AdminAssemblyDetailPage({
           stepFile: { select: { id: true } },
           drawingFile: { select: { id: true } },
           cutFile: { select: { id: true } },
+          thumbnailFile: { select: { id: true } },
         },
       },
     },
@@ -46,6 +47,7 @@ export default async function AdminAssemblyDetailPage({
         hasStep: !!p.stepFile,
         hasDrawing: !!p.drawingFile,
         hasCut: !!p.cutFile,
+        thumbnailFileId: p.thumbnailFile?.id ?? null,
         operationCount: p._count.operations,
       }))}
     />

app/admin/projects/[id]/assemblies/[assemblyId]/parts/[partId]/PartDetailClient.tsx

@@ -47,6 +47,7 @@ interface PartInfo {
   stepFile: FileView | null;
   drawingFile: FileView | null;
   cutFile: FileView | null;
+  thumbnailFileId: string | null;
 }
 
 export interface OperationRow {
@@ -208,7 +209,13 @@ export default function PartDetailClient({
       </section>
 
       {part.stepFile ? (
-        <StepViewerSection fileId={part.stepFile.id} fileName={part.stepFile.originalName} />
+        <StepViewerSection
+          partId={part.id}
+          fileId={part.stepFile.id}
+          fileName={part.stepFile.originalName}
+          hasThumbnail={!!part.thumbnailFileId}
+          onThumbnailSaved={() => router.refresh()}
+        />
       ) : null}
 
       <OperationsSection
@@ -676,27 +683,96 @@ function OperationModal({
 
 // -------- 3D viewer ------------------------------------------------------
 
-function StepViewerSection({ fileId, fileName }: { fileId: string; fileName: string }) {
+function StepViewerSection({
+  partId,
+  fileId,
+  fileName,
+  hasThumbnail,
+  onThumbnailSaved,
+}: {
+  partId: string;
+  fileId: string;
+  fileName: string;
+  hasThumbnail: boolean;
+  onThumbnailSaved: () => void;
+}) {
   const [open, setOpen] = useState(false);
   const [edges, setEdges] = useState(true);
+  const [savingThumb, setSavingThumb] = useState(false);
+  const [thumbMessage, setThumbMessage] = useState<string | null>(null);
+  // Bump this to force a remount of the viewer (and therefore a fresh
+  // first-frame capture). Used by "Regenerate thumbnail".
+  const [captureNonce, setCaptureNonce] = useState(0);
+  // One-shot guard so onFirstFrame from the render loop only fires once per
+  // viewer mount. Reset whenever captureNonce advances.
+  const capturedRef = useRef(false);
   // The viewer fetches via `/api/v1/files/:id/download`, which streams the
   // stored STEP bytes with correct auth (admin session cookie is already set).
   const url = `/api/v1/files/${fileId}/download`;
 
+  // Capture + upload the first-frame thumbnail. Runs at most once per open.
+  async function handleFirstFrame(blob: Blob) {
+    if (capturedRef.current) return;
+    capturedRef.current = true;
+    setSavingThumb(true);
+    setThumbMessage(null);
+    try {
+      const form = new FormData();
+      form.set("file", new File([blob], `part-${partId}.jpg`, { type: "image/jpeg" }));
+      const res = await apiFetch<{ file: { id: string } }>("/api/v1/files", {
+        method: "POST",
+        body: form,
+      });
+      await apiFetch(`/api/v1/parts/${partId}`, {
+        method: "PATCH",
+        body: JSON.stringify({ thumbnailFileId: res.file.id }),
+      });
+      setThumbMessage("Thumbnail saved.");
+      onThumbnailSaved();
+    } catch (err) {
+      setThumbMessage(
+        err instanceof ApiClientError ? `Thumbnail save failed: ${err.message}` : "Thumbnail save failed",
+      );
+    } finally {
+      setSavingThumb(false);
+    }
+  }
+
+  // Only request a new thumbnail if there isn't one already (or the user hit
+  // "Regenerate"), to avoid overwriting a good capture with a worse one every
+  // time someone opens the viewer.
+  const shouldCapture = open && (!hasThumbnail || captureNonce > 0) && !capturedRef.current;
+
   return (
     <section className="mb-8">
       <div className="flex items-center justify-between mb-3">
         <h2 className="text-lg font-semibold">3D viewer</h2>
         <div className="flex items-center gap-2">
           {open ? (
-            <label className="flex items-center gap-1.5 text-xs text-slate-600">
-              <input
-                type="checkbox"
-                checked={edges}
-                onChange={(e) => setEdges(e.target.checked)}
-              />
-              Show edges
-            </label>
+            <>
+              <label className="flex items-center gap-1.5 text-xs text-slate-600">
+                <input
+                  type="checkbox"
+                  checked={edges}
+                  onChange={(e) => setEdges(e.target.checked)}
+                />
+                Show edges
+              </label>
+              {hasThumbnail ? (
+                <Button
+                  variant="ghost"
+                  size="sm"
+                  disabled={savingThumb}
+                  onClick={() => {
+                    capturedRef.current = false;
+                    setThumbMessage("Regenerating on next frame…");
+                    setCaptureNonce((n) => n + 1);
+                  }}
+                >
+                  {savingThumb ? "Saving…" : "Regenerate thumbnail"}
+                </Button>
+              ) : null}
+            </>
           ) : null}
           <Button variant={open ? "secondary" : "primary"} size="sm" onClick={() => setOpen((v) => !v)}>
             {open ? "Hide" : "Show 3D"}
@@ -706,13 +782,21 @@ function StepViewerSection({ fileId, fileName }: { fileId: string; fileName: str
       {open ? (
         <Card>
           <div className="p-3">
-            <div className="mb-2 text-xs text-slate-500 truncate" title={fileName}>
-              Viewing: <code className="font-mono text-slate-700">{fileName}</code>
+            <div className="mb-2 flex items-center justify-between gap-3 text-xs text-slate-500">
+              <span className="truncate" title={fileName}>
+                Viewing: <code className="font-mono text-slate-700">{fileName}</code>
+              </span>
+              {thumbMessage ? <span className="text-slate-500">{thumbMessage}</span> : null}
             </div>
-            <StepViewer key={`${fileId}-${edges ? "e" : "ne"}`} url={url} showEdges={edges} />
+            <StepViewer
+              key={`${fileId}-${edges ? "e" : "ne"}-${captureNonce}`}
+              url={url}
+              showEdges={edges}
+              onFirstFrame={shouldCapture ? handleFirstFrame : undefined}
+            />
             <p className="mt-2 text-[11px] text-slate-500">
-              Drag to rotate · scroll to zoom · right-drag to pan. Parsing and rendering happens
-              in your browser — nothing is uploaded.
+              Drag to rotate · scroll to zoom · right-drag to pan. Parsing and rendering happen in
+              your browser; the first view also uploads a ~480×360 JPEG thumbnail for the parts list.
             </p>
           </div>
         </Card>

app/admin/projects/[id]/assemblies/[assemblyId]/parts/[partId]/page.tsx

@@ -25,6 +25,7 @@ export default async function AdminPartDetailPage({
         stepFile: true,
         drawingFile: true,
         cutFile: true,
+        thumbnailFile: true,
         operations: {
           orderBy: { sequence: "asc" },
           include: {
@@ -79,6 +80,7 @@ export default async function AdminPartDetailPage({
         stepFile: fileView(part.stepFile),
         drawingFile: fileView(part.drawingFile),
         cutFile: fileView(part.cutFile),
+        thumbnailFileId: part.thumbnailFileId,
       }}
       operations={part.operations.map((op) => ({
         id: op.id,

app/api/v1/parts/[id]/route.ts

@@ -51,6 +51,7 @@ export async function PATCH(req: NextRequest, ctx: { params: Promise<{ id: strin
         ...(body.stepFileId !== undefined ? { stepFileId: body.stepFileId } : {}),
         ...(body.drawingFileId !== undefined ? { drawingFileId: body.drawingFileId } : {}),
         ...(body.cutFileId !== undefined ? { cutFileId: body.cutFileId } : {}),
+        ...(body.thumbnailFileId !== undefined ? { thumbnailFileId: body.thumbnailFileId } : {}),
       },
     });
     await audit({