feat: enhance UI components with error handling and loading states; add EmptyState component for better user feedback

Author: tikazyq

.github/agents/code.agent.md

@@ -35,19 +35,26 @@ You implement features by following specs. Quality and spec compliance are non-n
 
 ```
 BEFORE: board → view <spec> → deps <spec> → update --status in-progress
-DURING: Code (follow spec) → Test → Document → Link deps
-AFTER: Check off items → validate → update --status complete
+DURING: Code → Check off completed items in spec → Test → Document progress in spec → Link deps
+AFTER: Verify all items checked → validate → update --status complete
 ```
 
+**CRITICAL:** Update the spec file AS YOU WORK:
+- Check off `- [ ]` items as you complete them
+- Add implementation notes in real-time
+- Document decisions, trade-offs, challenges DURING implementation
+- The spec is your working document, not just a reference
+
 ## Rules
 
 1. **NEVER edit frontmatter** - Use tools
 2. **ALWAYS update status first** - `in-progress` before coding
-3. **ALWAYS link references** - Connect related specs
-4. **ALWAYS document** - Decisions, learnings, trade-offs
-5. **ALWAYS complete checklist** - Every acceptance criteria
-6. **NEVER skip validation** - Run before marking complete
-7. **NO COMPROMISES** - Full spec implementation required
+3. **CHECK OFF ITEMS AS YOU GO** - Update `- [x]` in spec immediately after completing each task
+4. **UPDATE SPEC CONTINUOUSLY** - Document decisions, progress, learnings IN THE SPEC FILE as you work
+5. **ALWAYS link references** - Connect related specs
+6. **ALWAYS complete checklist** - Every acceptance criteria must be checked before marking complete
+7. **NEVER skip validation** - Run before marking complete
+8. **NO COMPROMISES** - Full spec implementation required
 
 ## Status Tracking
 
@@ -76,7 +83,8 @@ Completion verification: All checklist items must be checked. Use `--force` only
 
 ## Document Implementation
 
-Add to spec:
+**Update the spec file continuously during implementation:**
+
 ```markdown
 ## Implementation Notes
 - Approach taken
@@ -85,6 +93,14 @@ Add to spec:
 - Testing approach
 ```
 
+**As you complete each task:**
+1. Change `- [ ] Task` to `- [x] Task` in the spec
+2. Add notes about how it was done
+3. Document any deviations or learnings
+4. Keep the spec synchronized with actual progress
+
+**The spec is your implementation log, not a static document.**
+
 ---
 
 **Mission:** Deliver COMPLETE implementations that EXACTLY match spec requirements. NO compromises. NO workarounds. ALWAYS follow spec instructions.

.github/agents/review.agent.md

@@ -11,12 +11,13 @@ You validate completed specs, ensuring full implementation without compromises.
 
 ## Core Responsibilities
 
-1. **Verify completion** - All acceptance criteria met
-2. **Validate quality** - Implementation matches spec exactly
-3. **Check documentation** - Spec updated with details
-4. **Test functionality** - Features work as described
-5. **Verify claimed progress** - Status/todos/checkboxes match actual code/commits
-6. **Report issues** - Actionable feedback
+1. **Verify spec was updated DURING work** - Not just at the end, but continuously
+2. **Verify completion** - All acceptance criteria met
+3. **Validate quality** - Implementation matches spec exactly
+4. **Check documentation** - Spec updated with details as work progressed
+5. **Test functionality** - Features work as described
+6. **Verify claimed progress** - Status/todos/checkboxes match actual code/commits
+7. **Report issues** - Actionable feedback
 
 ## 🚨 CRITICAL: ZERO TOLERANCE FOR COMPROMISES
 
@@ -32,6 +33,28 @@ You validate completed specs, ensuring full implementation without compromises.
 - Flag any deviation from spec instructions
 - Reject work that compromises on spec requirements
 
+## ⚠️ VERIFY SPEC WAS UPDATED DURING WORK
+
+**The spec must be a living document, not updated only at completion:**
+
+**Check git history of the spec file:**
+- `git log --oneline specs/NNN-name/README.md` - Multiple commits during implementation?
+- Spec updated incrementally as work progressed?
+- Checkboxes checked off throughout, not all at once at the end?
+- Implementation notes added during work, not just at completion?
+
+**Red flags (REJECT if found):**
+- All checkboxes changed from `[ ]` to `[x]` in a single commit at the end
+- No spec file updates between "in-progress" and "complete" status changes
+- Implementation notes all added in one final commit
+- Git history shows spec untouched during days/weeks of implementation work
+
+**Proper pattern:**
+- Regular commits updating spec file throughout implementation
+- Checkboxes checked off as each task completes
+- Implementation notes added when decisions are made
+- Spec evolves alongside code development
+
 ## ⚠️ VERIFY CLAIMED PROGRESS
 
 **Specs must reflect reality:**
@@ -43,7 +66,8 @@ You validate completed specs, ensuring full implementation without compromises.
 - No stale specs (code changed but spec not updated)
 
 **Cross-check against:**
-- `git log` - Recent commits for this spec's files
+- `git log specs/NNN-name/README.md` - Spec updated throughout work, not just at end?
+- `git log --since="<date spec marked in-progress>"` - Work commits align with spec updates?
 - `git diff` - Changes since spec marked in-progress
 - `grep_search` - Verify mentioned files/functions exist
 - `read_file` - Check implementation details match spec claims
@@ -53,13 +77,14 @@ You validate completed specs, ensuring full implementation without compromises.
 
 ```
 1. Assess: view → validate → validate --check-deps
-2. Verify Progress: git log → git diff → grep claimed files/features
-3. Criteria: ALL items checked? Test each manually
-4. Code: Matches spec EXACTLY? Tests pass? Quality OK?
-5. Docs: Implementation notes? Decisions documented?
-6. Test: Run feature, test edge cases, verify errors
-7. Dependencies: deps → verify complete
-8. Report: APPROVED / NEEDS WORK + specific issues
+2. Verify Spec History: git log specs/NNN/README.md → Check incremental updates
+3. Verify Progress: git log → git diff → grep claimed files/features
+4. Criteria: ALL items checked? Test each manually
+5. Code: Matches spec EXACTLY? Tests pass? Quality OK?
+6. Docs: Implementation notes? Decisions documented?
+7. Test: Run feature, test edge cases, verify errors
+8. Dependencies: deps → verify complete
+9. Report: APPROVED / NEEDS WORK + specific issues
 ```
 
 ## Tools
@@ -68,6 +93,7 @@ You validate completed specs, ensuring full implementation without compromises.
 
 ## Review Checklist
 
+**Spec Update History:** Git log shows incremental spec updates? Checkboxes checked throughout? Implementation notes added during work? Not all updated at the end?
 **Claimed Progress:** Status matches code? Checked items have implementation? Commits align? Files exist? No phantom progress?
 **Spec:** All criteria checked, status complete, implementation notes, decisions, learnings
 **Code:** Matches spec intent EXACTLY, tests pass, proper errors, follows conventions
@@ -78,14 +104,15 @@ You validate completed specs, ensuring full implementation without compromises.
 
 ## Common Issues
 
-Phantom progress (checked without code), stale specs (code changed but spec not updated), status mismatch (complete but features missing), unchecked items, manual frontmatter edits, missing impl notes, broken deps, token bloat, missing tests, missing translations
+Bulk spec updates at end (all checkboxes in one commit), phantom progress (checked without code), stale specs (code changed but spec not updated), status mismatch (complete but features missing), unchecked items, manual frontmatter edits, missing impl notes, broken deps, token bloat, missing tests, missing translations
 
 ## Report Format
 
 ```markdown
 # Review: [Spec]
 **Status**: APPROVED ✅ | NEEDS WORK ❌
 
+## Spec Update History: Incremental updates? Or bulk at end?
 ## Progress Verification: Status matches code? Commits align? Files exist?
 ## Criteria: [x/y] checked
 ## Code: Matches spec? Tests pass?
@@ -98,19 +125,20 @@ Phantom progress (checked without code), stale specs (code changed but spec not
 
 ## Approval Criteria
 
-✅ **APPROVE:** Claimed progress verified against code/commits, all criteria met, code matches spec exactly, tests pass, docs complete
-❌ **NEEDS WORK:** Phantom progress, status mismatch, criteria unchecked, doesn't match spec, compromises/workarounds found, tests fail
+✅ **APPROVE:** Spec updated incrementally during work (not bulk at end), claimed progress verified against code/commits, all criteria met, code matches spec exactly, tests pass, docs complete
+❌ **NEEDS WORK:** Bulk spec updates at completion, phantom progress, status mismatch, criteria unchecked, doesn't match spec, compromises/workarounds found, tests fail
 
 ## Standards
 
-1. Verify claimed progress against actual code/commits first
-2. Thorough but fair
-3. Specific with file/line refs
-4. Actionable fixes
-5. Reject compromises
-6. Verify complete implementation
-7. Keep specs synchronized with reality
+1. Check spec git history FIRST - incremental updates or bulk at end?
+2. Verify claimed progress against actual code/commits
+3. Thorough but fair
+4. Specific with file/line refs
+5. Actionable fixes
+6. Reject compromises
+7. Verify complete implementation
+8. Keep specs synchronized with reality
 
 ---
 
-**Mission:** Ensure specs represent COMPLETE, WORKING features that match actual implementation. REJECT compromises and workarounds. VERIFY full spec implementation. PREVENT phantom progress and stale specs.
+**Mission:** Ensure specs were UPDATED DURING WORK (not bulk at end), represent COMPLETE, WORKING features that match actual implementation. REJECT compromises and workarounds. VERIFY full spec implementation. PREVENT phantom progress, bulk updates, and stale specs.

packages/ui-vite/src/components/Layout.tsx

@@ -1,8 +1,11 @@
-import { Outlet } from 'react-router-dom';
+import { Outlet, useLocation } from 'react-router-dom';
 import { useState } from 'react';
 import { Navigation } from './Navigation';
 import { MainSidebar } from './MainSidebar';
 import { useGlobalShortcuts } from '../hooks/useKeyboardShortcuts';
+import { ErrorBoundary } from './shared/ErrorBoundary';
+import { PageTransition } from './shared/PageTransition';
+import { BackToTop } from './shared/BackToTop';
 
 function KeyboardShortcutsHelp({ onClose }: { onClose: () => void }) {
   const shortcuts = [
@@ -40,6 +43,7 @@ function KeyboardShortcutsHelp({ onClose }: { onClose: () => void }) {
 
 export function Layout() {
   const [showShortcuts, setShowShortcuts] = useState(false);
+  const location = useLocation();
 
   // Register global keyboard shortcuts
   useGlobalShortcuts();
@@ -50,10 +54,15 @@ export function Layout() {
       <div className="flex w-full min-w-0">
         <MainSidebar />
         <main className="flex-1 min-w-0 w-full lg:w-[calc(100vw-var(--main-sidebar-width,240px))] px-4 py-6 lg:px-6">
-          <Outlet />
+          <ErrorBoundary key={location.pathname} onReset={() => window.location.reload()}>
+            <PageTransition>
+              <Outlet />
+            </PageTransition>
+          </ErrorBoundary>
         </main>
       </div>
       {showShortcuts && <KeyboardShortcutsHelp onClose={() => setShowShortcuts(false)} />}
+      <BackToTop />
     </div>
   );
 }

packages/ui-vite/src/components/context/ContextClient.tsx

@@ -135,8 +135,19 @@ export function ContextClient({ projectRoot }: ContextClientProps) {
         </CardHeader>
         <CardContent>
           {files.length === 0 ? (
-            <div className="text-center py-8 text-muted-foreground text-sm">
-              No context files found in .lean-spec/context
+            <div className="text-center py-8 text-muted-foreground text-sm space-y-3">
+              <div>No context files found in .lean-spec/context.</div>
+              <Button size="sm" variant="secondary" onClick={loadList}>
+                <RefreshCcw className="h-4 w-4 mr-2" />
+                Rescan project
+              </Button>
+            </div>
+          ) : groupedFiles.length === 0 ? (
+            <div className="text-center py-8 text-muted-foreground text-sm space-y-3">
+              <div>No files match this search.</div>
+              <Button size="sm" variant="outline" onClick={() => setSearch('')}>
+                Clear search
+              </Button>
             </div>
           ) : (
             <div className="space-y-4 max-h-[70vh] overflow-y-auto pr-1">

packages/ui-vite/src/components/context/ContextFileDetail.tsx

@@ -6,7 +6,6 @@ import rehypeSlug from 'rehype-slug';
 import { ArrowLeft, Clock, Copy, ExternalLink, FileText, Hash, Layers, Type } from 'lucide-react';
 import { Badge, Button, Card, CardContent } from '@leanspec/ui-components';
 import { TableOfContents, TableOfContentsSidebar } from '../spec-detail/TableOfContents';
-import { BackToTop } from '../shared/BackToTop';
 import { MermaidDiagram } from '../MermaidDiagram';
 import type { ContextFileContent } from '../../lib/api';
 
@@ -163,8 +162,6 @@ export function ContextFileDetail({ file, projectRoot, onBack }: ContextFileDeta
           <TableOfContents content={headingContent} />
         </div>
       )}
-
-      <BackToTop />
     </div>
   );
 }

packages/ui-vite/src/components/shared/EmptyState.tsx

@@ -0,0 +1,35 @@
+import type { LucideIcon } from 'lucide-react';
+import { Card, CardContent, Button } from '@leanspec/ui-components';
+import { cn } from '../../lib/utils';
+import type { ReactNode } from 'react';
+
+interface EmptyStateProps {
+  icon: LucideIcon;
+  title: string;
+  description?: string;
+  actions?: ReactNode;
+  className?: string;
+  tone?: 'muted' | 'error';
+}
+
+export function EmptyState({ icon: Icon, title, description, actions, className, tone = 'muted' }: EmptyStateProps) {
+  return (
+    <Card className={cn('border-dashed', className)}>
+      <CardContent className="py-10 text-center space-y-3">
+        <div className="flex justify-center">
+          <Button
+            size="icon"
+            variant={tone === 'error' ? 'destructive' : 'secondary'}
+            className="h-10 w-10 rounded-full"
+            aria-label={title}
+          >
+            <Icon className="h-5 w-5" />
+          </Button>
+        </div>
+        <div className="text-lg font-semibold">{title}</div>
+        {description && <p className="text-sm text-muted-foreground max-w-xl mx-auto">{description}</p>}
+        {actions && <div className="flex justify-center gap-2 flex-wrap pt-1">{actions}</div>}
+      </CardContent>
+    </Card>
+  );
+}

packages/ui-vite/src/components/shared/ErrorBoundary.tsx

@@ -0,0 +1,58 @@
+import { Component, type ErrorInfo, type ReactNode } from 'react';
+import { AlertTriangle } from 'lucide-react';
+import { Button } from '@leanspec/ui-components';
+import { EmptyState } from './EmptyState';
+
+interface Props {
+  children: ReactNode;
+  title?: string;
+  message?: string;
+  onReset?: () => void;
+}
+
+interface State {
+  hasError: boolean;
+  error?: Error;
+}
+
+export class ErrorBoundary extends Component<Props, State> {
+  state: State = { hasError: false };
+
+  static getDerivedStateFromError(error: Error): State {
+    return { hasError: true, error };
+  }
+
+  componentDidCatch(error: Error, errorInfo: ErrorInfo) {
+    console.error('UI error captured', error, errorInfo);
+  }
+
+  resetBoundary = () => {
+    this.setState({ hasError: false, error: undefined });
+    this.props.onReset?.();
+  };
+
+  render() {
+    if (this.state.hasError) {
+      return (
+        <EmptyState
+          icon={AlertTriangle}
+          title={this.props.title || 'Something went wrong'}
+          description={this.props.message || this.state.error?.message || 'The page failed to render.'}
+          tone="error"
+          actions={(
+            <>
+              <Button size="sm" onClick={this.resetBoundary}>
+                Retry
+              </Button>
+              <Button size="sm" variant="outline" onClick={() => window.location.reload()}>
+                Reload page
+              </Button>
+            </>
+          )}
+        />
+      );
+    }
+
+    return this.props.children;
+  }
+}