Feat/dashboard wallets loading error pnpm (#588)

* feat: prefetch wallets on sidebar hover

Warms the /dashboard/wallets route chunk and its API data as soon as
the user hovers or focuses the Wallets sidebar link, via a new
deduped wallets prefetch cache (src/lib/walletsPrefetchCache.ts) that
useWallets() now reuses on initial mount instead of firing a
duplicate request. Adds Vitest/RTL coverage for the hover/focus
prefetch behavior and the cache's dedupe/error-recovery logic.

* feat: add route-level loading.tsx for dashboard

Adds src/app/dashboard/loading.tsx so Next.js shows an accessible
skeleton (reusing the existing Skeleton primitive) as the Suspense
fallback while any /dashboard/** route segment is loading, instead of
a blank screen. Includes Vitest/RTL coverage and a README (diff is
under 150 lines) documenting the change and a manual test checklist.

* feat: add ErrorBoundary around dashboard pages

Adds src/app/dashboard/error.tsx (Next.js segment error boundary) plus
a reusable DashboardErrorBoundary component that logs the error and
renders the existing ErrorState primitive with a retry action. Because
it lives alongside the dashboard layout, the sidebar/topbar stay
mounted on error so navigation isn't lost. Includes Vitest/RTL
coverage and a README (diff is under 150 lines) with a manual test
checklist.

* chore: keep pnpm lockfile as the only package lock

Enforces pnpm as the sole installer via: a packageManager field +
engines block in package.json, a preinstall guard script that fails
npm/yarn installs before they can generate a lockfile, .npmrc's
package-manager-strict/engine-strict, .gitignore rules for
yarn.lock/npm-shrinkwrap.json, and a new CI step that fails the build
if a non-pnpm lockfile is present. Includes a Vitest check and a
README (diff is under 150 lines) with a manual test checklist.

Author: james2177

.github/workflows/ci.yml

@@ -30,6 +30,13 @@ jobs:
           node-version: "22"
           cache: "pnpm"
 
+      - name: Verify pnpm lockfile is the only lockfile
+        run: |
+          if [ -f package-lock.json ] || [ -f yarn.lock ] || [ -f npm-shrinkwrap.json ]; then
+            echo "::error::Found a non-pnpm lockfile. This repo only tracks pnpm-lock.yaml."
+            exit 1
+          fi
+
       - name: Install dependencies
         run: pnpm install --frozen-lockfile
 

.gitignore

@@ -3,6 +3,8 @@
 # dependencies
 /node_modules
 /package-lock.json
+/npm-shrinkwrap.json
+/yarn.lock
 /.pnp
 .pnp.*
 .yarn/*
@@ -11,6 +13,8 @@
 !.yarn/releases
 !.yarn/versions
 
+# pnpm-lock.yaml is the only package lockfile this repo tracks.
+
 # testing
 /coverage
 /playwright-report

.npmrc

@@ -0,0 +1,6 @@
+# Enforce the "packageManager" field in package.json so corepack refuses
+# to run this project with the wrong pnpm version.
+package-manager-strict=true
+
+# Fail installs when the current Node/pnpm doesn't satisfy "engines".
+engine-strict=true

ERROR_BOUNDARY_README.md

@@ -0,0 +1,40 @@
+# ErrorBoundary around dashboard pages
+
+## What was implemented
+
+- `src/components/dashboard/DashboardErrorBoundary.tsx` — a client
+  component that logs the caught error (`console.error`, same pattern as
+  the existing root-level `GlobalErrorBoundary`) and renders the existing
+  `ErrorState` UI primitive (`src/components/ui/ErrorState.tsx`) with a
+  "Try again" action wired to Next's `reset()`.
+- `src/app/dashboard/error.tsx` — the Next.js App Router segment error
+  file. Next automatically wraps `src/app/dashboard/layout.tsx`'s children
+  in an error boundary that renders this component whenever a rendering
+  error is thrown anywhere under `/dashboard/**` that isn't already caught
+  by a more specific `error.tsx`.
+- `src/components/dashboard/__tests__/DashboardErrorBoundary.test.tsx` —
+  covers: error message rendering, the retry button invoking `reset()`, the
+  fallback copy when `error.message` is empty, and that the error is logged.
+
+## Why this is scoped correctly
+
+Because `error.tsx` lives in the same segment as `layout.tsx`
+(`src/app/dashboard/`), the `DashboardLayout` (sidebar + topbar) stays
+mounted when a page throws - only the page content area is replaced with
+the error UI. This avoids the "No regressions in closely related dashboard
+navigation" failure mode: the sidebar's links (including the wallets
+prefetch-on-hover behavior) keep working even while one page is in an error
+state, so the user can navigate away without a full reload.
+
+This complements, rather than duplicates, the existing root-level
+`src/app/error.tsx` + `GlobalErrorBoundary`, which still catches errors
+thrown outside of `/dashboard` (or inside `layout.tsx`/`RootLayout` itself).
+
+## Manual verification checklist
+
+- [ ] Temporarily `throw new Error("test")` inside a dashboard page body,
+      confirm the dashboard error UI renders with sidebar still visible.
+- [ ] Click "Try again" and confirm `reset()` re-renders the segment.
+- [ ] Check on a narrow mobile viewport (375px) - error card doesn't
+      overflow horizontally.
+- [ ] Confirm the error is logged to the console for observability.

PNPM_LOCKFILE_README.md

@@ -0,0 +1,45 @@
+# Keep pnpm lockfile as the only package lock
+
+## What was implemented
+
+- `package.json` — added `"packageManager": "pnpm@9.15.4"` (enables
+  Corepack to enforce the exact pnpm version) and an `engines` block that
+  fails npm/yarn with an explicit `please-use-pnpm` message if someone tries
+  to install with them directly. Added a `preinstall` script that runs
+  `scripts/verify-pnpm.js`.
+- `scripts/verify-pnpm.js` — inspects `npm_config_user_agent` (set by every
+  package manager) at install time and hard-fails with instructions if the
+  installer isn't pnpm. This is the first line of defense - it fires before
+  any dependency resolution happens, so a `npm install` never gets far
+  enough to generate a `package-lock.json`.
+- `.npmrc` — sets `package-manager-strict=true` (Corepack enforces the
+  `packageManager` field) and `engine-strict=true`.
+- `.gitignore` — explicitly ignores `/yarn.lock` and `/npm-shrinkwrap.json`
+  in addition to the pre-existing `/package-lock.json` rule, so an
+  accidental lockfile from another package manager can never be committed.
+- `.github/workflows/ci.yml` — added a "Verify pnpm lockfile is the only
+  lockfile" step that fails the build if `package-lock.json`, `yarn.lock`,
+  or `npm-shrinkwrap.json` exist in the repo, before `pnpm install
+  --frozen-lockfile` runs.
+- `src/lib/__tests__/pnpmLockfile.test.ts` — Vitest coverage asserting
+  `pnpm-lock.yaml` exists, that no competing lockfiles exist, and that
+  `package.json` declares a `pnpm@` `packageManager`.
+
+## Why
+
+Multiple lockfiles (e.g. a stray `package-lock.json` committed by someone
+running plain `npm install`) cause dependency resolution to silently drift
+between contributors/CI and can reintroduce vulnerable or duplicate
+transitive versions that `pnpm-lock.yaml` had already deduped/pinned. This
+change makes pnpm the only supported installer at three layers: local
+install-time (`preinstall` script + Corepack), source control
+(`.gitignore`), and CI (explicit lockfile check + `--frozen-lockfile`).
+
+## Manual verification checklist
+
+- [ ] Run `npm install` locally - it should fail immediately with the
+      "This repository only supports pnpm" message.
+- [ ] Run `pnpm install` - it should proceed normally.
+- [ ] Confirm CI's new "Verify pnpm lockfile is the only lockfile" step
+      passes on a clean checkout.
+- [ ] `pnpm test -- pnpmLockfile` passes locally.

ROUTE_LOADING_README.md

@@ -0,0 +1,37 @@
+# Route-level loading.tsx for /dashboard
+
+## What was implemented
+
+- `src/app/dashboard/loading.tsx` — a Next.js App Router segment loading
+  file that Next automatically wraps around `src/app/dashboard/layout.tsx`'s
+  children in a `<Suspense>` boundary. It renders while a dashboard route
+  segment (and any nested segment without its own `loading.tsx`, e.g.
+  `/dashboard/users`) is being fetched/streamed in on navigation.
+- Reuses the existing `Skeleton` primitive (`src/components/ui/Skeleton.tsx`)
+  so the placeholder matches the visual language already used elsewhere
+  (e.g. `src/app/demo/dashboard/loading.tsx`, `WalletTableSkeleton`).
+- Marked with `role="status"`, `aria-busy="true"`, `aria-live="polite"`, and a
+  screen-reader-only label so assistive tech announces the loading state
+  (matches the accessibility pattern already used in `WalletDetailSkeleton`).
+- `src/app/dashboard/__tests__/loading.test.tsx` — Vitest/RTL coverage
+  asserting the accessible status region and that skeleton placeholders are
+  rendered instead of empty content.
+
+## Why this doesn't affect existing pages
+
+Pages like `/dashboard/wallets` already manage their own client-side
+loading/empty/error states via `useWallets()`. The new `loading.tsx` only
+governs the Next.js navigation-time Suspense fallback (i.e. the moment
+between clicking a sidebar link and the new route's JS/RSC payload
+resolving) - it does not replace or conflict with in-page data-fetching
+states.
+
+## Manual verification checklist
+
+- [ ] Throttle network in devtools, navigate between `/dashboard` and a
+      nested route (e.g. `/dashboard/users`) - skeleton briefly appears.
+- [ ] Confirm sidebar/topbar remain visible during the loading state (layout
+      stays mounted since `loading.tsx` sits below `layout.tsx`).
+- [ ] Check on a narrow mobile viewport (375px) - skeleton layout doesn't
+      overflow horizontally.
+- [ ] Verify with a screen reader that the loading state is announced.

package.json

@@ -6,6 +6,7 @@
 		"node": ">=22"
 	},
 	"scripts": {
+		"preinstall": "node ./scripts/verify-pnpm.js",
 		"dev": "next dev",
 		"build": "next build",
 		"start": "next start",

scripts/verify-pnpm.js

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+/**
+ * Fails fast if this project is being installed with npm or yarn.
+ * pnpm-lock.yaml is the single source of truth for dependency
+ * resolution here - a stray package-lock.json/yarn.lock causes
+ * dependency drift between contributors and CI.
+ */
+
+const userAgent = process.env.npm_config_user_agent || "";
+
+if (!userAgent.startsWith("pnpm")) {
+	console.error("\n  ⛔  This repository only supports pnpm.\n");
+	console.error(
+		`      Detected package manager: ${userAgent.split("/")[0] || "unknown"}`,
+	);
+	console.error("      Please run: pnpm install\n");
+	console.error(
+		"      If pnpm isn't installed: corepack enable && corepack prepare pnpm@9.15.4 --activate\n",
+	);
+	process.exit(1);
+}

src/app/dashboard/__tests__/loading.test.tsx

@@ -0,0 +1,19 @@
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+import DashboardRouteLoading from "../loading";
+
+describe("DashboardRouteLoading", () => {
+	it("renders an accessible busy status region", () => {
+		render(<DashboardRouteLoading />);
+
+		const status = screen.getByRole("status", { name: /loading dashboard/i });
+		expect(status).toHaveAttribute("aria-busy", "true");
+		expect(status).toHaveAttribute("aria-live", "polite");
+	});
+
+	it("renders skeleton placeholders instead of empty content", () => {
+		render(<DashboardRouteLoading />);
+
+		expect(screen.getAllByTestId("skeleton").length).toBeGreaterThan(0);
+	});
+});

src/app/dashboard/error.tsx

@@ -0,0 +1,13 @@
+"use client";
+
+import { DashboardErrorBoundary } from "@/components/dashboard/DashboardErrorBoundary";
+
+export default function DashboardError({
+	error,
+	reset,
+}: {
+	error: Error & { digest?: string };
+	reset: () => void;
+}) {
+	return <DashboardErrorBoundary error={error} reset={reset} />;
+}