feat(demo): add builder gallery

.changeset/widget-react-dev-stack.md

@@ -0,0 +1,5 @@
+---
+'@usdh-kit/widget': patch
+---
+
+Align widget development React dependencies with the wallet stack used by the demo gallery.

README.md

@@ -22,6 +22,7 @@ TypeScript SDK for USDH on Hyperliquid.
 USDH is the native stablecoin on Hyperliquid, issued by Bridge and designed by Native Markets, with 50% of reserve revenue routed to the Hyperliquid Assistance Fund. `@usdh-kit/sdk` ships the retail-side plumbing (pair resolution, signing, transport) so apps and bots can convert into USDH without writing the Hyperliquid action layer themselves. `@usdh-kit/widget` is an embeddable React component on top of the SDK so dapps can drop in a swap form in a few lines.
 
 - **Source:** [github.com/sumfxn/usdh-kit](https://github.com/sumfxn/usdh-kit)
+- **Builder gallery:** [`apps/demo`](./apps/demo) — SDK surfaces, live read-only market board, examples, and widget showcase.
 - **Issues:** [github.com/sumfxn/usdh-kit/issues](https://github.com/sumfxn/usdh-kit/issues)
 - **USDH:** [usdh.com](https://usdh.com) (issued by [Bridge](https://bridge.xyz), designed by [Native Markets](https://www.nativemarkets.com))
 - **Hyperliquid:** [hyperliquid.xyz](https://hyperliquid.xyz) · [docs](https://hyperliquid.gitbook.io/hyperliquid-docs)

apps/demo/README.md

@@ -1,6 +1,8 @@
-# demo
+# builder gallery
 
-Public Next.js dApp showcasing usdh-kit. Wallet connection (wagmi + ConnectKit) and swap UI land in follow-up PRs; this is the scaffold.
+Public Next.js app for the `usdh-kit` builder gallery. The first screen is a
+reference console for USDH/HIP-4 builders: SDK surfaces, read-only market data,
+example paths, and the embeddable swap widget.
 
 ## Run locally
 
@@ -11,14 +13,31 @@ pnpm --filter @usdh-kit-apps/demo dev
 
 Then open http://localhost:3000.
 
-## Stack
+## Data policy
 
-- Next.js 15 App Router + Turbopack
-- Tailwind CSS
-- React 19
+The gallery is safe by default:
 
-## Roadmap
+- live data is read-only and server-side
+- live reads happen at request time, not during `next build`
+- no `/exchange` calls are made for gallery data
+- no wallet connection is required to render the page
+- if Hyperliquid reads fail, the page falls back to sample data
 
-- PR2: wagmi + ConnectKit wiring, kit-context hook
-- PR3: swap UI (amount input, quote display, bridge + swap flow)
-- PR4: design polish (typography, motion, error states)
+The widget section remains interactive and uses the connected wallet only when a
+user explicitly starts the widget flow.
+
+## Stack note
+
+The demo uses Next.js 15 backport releases with React 18. Next 15 was already in
+the app before the gallery work; React 18 keeps the wallet stack aligned with
+ConnectKit's published peer dependencies.
+
+## Validation
+
+```sh
+pnpm --filter @usdh-kit-apps/demo typecheck
+pnpm --filter @usdh-kit-apps/demo build
+```
+
+The root `pnpm build` and `pnpm typecheck` commands also include this app so the
+public gallery cannot drift outside CI.

apps/demo/next-env.d.ts

@@ -1,5 +1,6 @@
 /// <reference types="next" />
 /// <reference types="next/image-types/global" />
+/// <reference path="./.next/types/routes.d.ts" />
 
 // NOTE: This file should not be edited
 // see https://nextjs.org/docs/app/api-reference/config/typescript for more information.

apps/demo/next.config.ts

@@ -8,9 +8,8 @@ const repoRoot = resolve(demoDir, '../..')
 
 const config: NextConfig = {
   reactStrictMode: true,
-  experimental: {
-    typedRoutes: true,
-  },
+  typedRoutes: true,
+  outputFileTracingRoot: repoRoot,
   webpack: (webpackConfig) => {
     webpackConfig.resolve ??= {}
     webpackConfig.resolve.extensionAlias = {
@@ -23,6 +22,7 @@ const config: NextConfig = {
       '@usdh-kit/sdk$': resolve(repoRoot, 'packages/sdk/src/index.ts'),
       '@usdh-kit/widget$': resolve(repoRoot, 'packages/widget/src/index.ts'),
       '@usdh-kit/widget/styles.css$': resolve(repoRoot, 'packages/widget/src/styles.css'),
+      'pino-pretty': false,
     }
     return webpackConfig
   },

apps/demo/package.json

@@ -14,16 +14,17 @@
     "@usdh-kit/sdk": "workspace:*",
     "@usdh-kit/widget": "workspace:*",
     "connectkit": "1.8.2",
-    "next": "15.1.0",
-    "react": "19.0.0",
-    "react-dom": "19.0.0",
+    "lucide-react": "1.14.0",
+    "next": "15.5.18",
+    "react": "18.3.1",
+    "react-dom": "18.3.1",
     "viem": "2.21.55",
     "wagmi": "2.14.6"
   },
   "devDependencies": {
     "@types/node": "22.10.2",
-    "@types/react": "19.0.1",
-    "@types/react-dom": "19.0.2",
+    "@types/react": "18.3.18",
+    "@types/react-dom": "18.3.5",
     "autoprefixer": "10.4.20",
     "postcss": "8.4.49",
     "tailwindcss": "3.4.17",

apps/demo/src/app/globals.css

@@ -8,14 +8,32 @@
 
 html,
 body {
-  background: #ffffff;
+  background: #f7f7f6;
   color: #171717;
 }
 
+html {
+  scroll-behavior: smooth;
+}
+
+body {
+  text-rendering: optimizeLegibility;
+}
+
+::selection {
+  background: #171717;
+  color: #ffffff;
+}
+
 @media (prefers-color-scheme: dark) {
   html,
   body {
-    background: #0a0a0a;
+    background: #080808;
     color: #f5f5f5;
   }
+
+  ::selection {
+    background: #f5f5f5;
+    color: #080808;
+  }
 }

apps/demo/src/app/layout.tsx

@@ -1,19 +1,24 @@
-import type { Metadata } from 'next'
+import type { Metadata, Viewport } from 'next'
 import type { ReactNode } from 'react'
 
 import { Providers } from '../components/Providers'
 import './globals.css'
 import '../../../../packages/widget/src/styles.css'
 
 export const metadata: Metadata = {
-  title: 'usdh-kit demo',
-  description: 'Swap stables into USDH on Hyperliquid, end-to-end demo',
+  title: 'usdh-kit builder gallery',
+  description: 'SDK and widget reference gallery for USDH builders on Hyperliquid',
+}
+
+export const viewport: Viewport = {
+  width: 'device-width',
+  initialScale: 1,
 }
 
 export default function RootLayout({ children }: { children: ReactNode }) {
   return (
     <html lang="en">
-      <body className="min-h-screen antialiased font-sans">
+      <body className="min-h-screen overflow-x-hidden antialiased font-sans">
         <Providers>{children}</Providers>
       </body>
     </html>