feat: Offline-First PWA with a Persistent Transaction Queue

.github/workflows/ci.yml

@@ -22,20 +22,32 @@ jobs:
         uses: actions/setup-node@v4
         with:
           node-version: ${{ matrix.node-version }}
-          cache: 'npm'
 
-      - name: Cache node_modules
+      - name: Cache npm dependencies
         id: cache-node-modules
         uses: actions/cache@v4
         with:
-          path: node_modules
+          path: |
+            node_modules
+            ~/.npm
           key: node-modules-${{ runner.os }}-node${{ matrix.node-version }}-${{ hashFiles('package-lock.json') }}
           restore-keys: |
             node-modules-${{ runner.os }}-node${{ matrix.node-version }}-
+            node-modules-${{ runner.os }}-
 
       - name: Install dependencies
         run: npm ci
 
+      - name: Cache Next.js build output
+        uses: actions/cache@v4
+        with:
+          path: |
+            .next/cache
+          key: nextjs-${{ runner.os }}-node${{ matrix.node-version }}-${{ hashFiles('package-lock.json') }}-${{ hashFiles('pages/**/*.tsx', 'pages/**/*.ts', 'components/**/*.tsx', 'components/**/*.ts') }}
+          restore-keys: |
+            nextjs-${{ runner.os }}-node${{ matrix.node-version }}-
+            nextjs-${{ runner.os }}-
+
       - name: Verify contract bindings are up-to-date
         run: npm run codegen:validate
 

components/atoms/index.tsx

@@ -10,3 +10,4 @@ export * from './toast'
 export * from './theme-toggle'
 export * from './spacer'
 export * from './markdown-renderer'
+export * from './offline-banner'

components/atoms/offline-banner/index.tsx

@@ -0,0 +1,40 @@
+import React from 'react'
+import styles from './style.module.css'
+import { useOnlineStatus } from '../../../hooks/useOnlineStatus'
+
+interface OfflineBannerProps {
+  /** Number of pending transactions in the queue. */
+  pendingCount?: number
+}
+
+/**
+ * A prominent banner that slides in when the browser goes offline,
+ * showing the current connectivity status and pending transaction count.
+ *
+ * When the user comes back online, the banner slides out (via CSS transition).
+ */
+export function OfflineBanner({ pendingCount = 0 }: OfflineBannerProps) {
+  const isOnline = useOnlineStatus()
+
+  if (isOnline) return null
+
+  return (
+    <div className={styles.banner} role="alert" aria-live="assertive">
+      <div className={styles.content}>
+        <span className={styles.icon} aria-hidden="true">📡</span>
+        <div className={styles.text}>
+          <span className={styles.title}>You are offline</span>
+          <span className={styles.subtitle}>
+            {pendingCount > 0
+              ? `${pendingCount} transaction(s) queued — they will be processed once you reconnect.`
+              : 'Some features may be unavailable until you reconnect.'}
+          </span>
+        </div>
+        <div className={styles.indicator}>
+          <span className={styles.dot} />
+          <span className={styles.label}>Offline</span>
+        </div>
+      </div>
+    </div>
+  )
+}

components/atoms/offline-banner/style.module.css

@@ -0,0 +1,118 @@
+.banner {
+  position: sticky;
+  top: 64px; /* below the navbar */
+  z-index: 40;
+  width: 100%;
+  background: linear-gradient(135deg, #f59e0b, #d97706);
+  box-shadow: 0 4px 24px rgba(217, 119, 6, 0.3);
+  animation: slideDown 0.3s ease-out;
+}
+
+.content {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  max-width: 1200px;
+  margin: 0 auto;
+  padding: 10px 24px;
+}
+
+.icon {
+  font-size: 1.25rem;
+  flex-shrink: 0;
+}
+
+.text {
+  flex: 1;
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+}
+
+.title {
+  font-weight: 700;
+  font-size: 0.875rem;
+  color: #1c1917;
+}
+
+.subtitle {
+  font-size: 0.75rem;
+  color: #44403c;
+  line-height: 1.4;
+}
+
+.indicator {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  flex-shrink: 0;
+  padding: 4px 12px;
+  background: rgba(0, 0, 0, 0.15);
+  border-radius: 999px;
+}
+
+.dot {
+  width: 8px;
+  height: 8px;
+  border-radius: 50%;
+  background: #dc2626;
+  animation: pulse 2s infinite;
+}
+
+@keyframes pulse {
+  0%, 100% { opacity: 1; }
+  50% { opacity: 0.4; }
+}
+
+.label {
+  font-size: 0.75rem;
+  font-weight: 600;
+  color: #1c1917;
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+}
+
+@keyframes slideDown {
+  from {
+    opacity: 0;
+    transform: translateY(-100%);
+  }
+  to {
+    opacity: 1;
+    transform: translateY(0);
+  }
+}
+
+/* Dark mode support */
+:global(.dark) .banner {
+  background: linear-gradient(135deg, #92400e, #78350f);
+  box-shadow: 0 4px 24px rgba(146, 64, 14, 0.4);
+}
+
+:global(.dark) .title {
+  color: #fef3c7;
+}
+
+:global(.dark) .subtitle {
+  color: #fde68a;
+}
+
+:global(.dark) .indicator {
+  background: rgba(255, 255, 255, 0.1);
+}
+
+:global(.dark) .label {
+  color: #fef3c7;
+}
+
+@media (max-width: 640px) {
+  .content {
+    flex-wrap: wrap;
+    padding: 8px 16px;
+    gap: 8px;
+  }
+
+  .text {
+    min-width: 0;
+  }
+}

components/molecules/index.tsx

@@ -8,3 +8,4 @@ export * from './markdown-editor'
 export * from './deliverable-viewer'
 export * from './dashboard-sidebar'
 export * from './dispute-event-feed'
+export * from './transaction-queue'