### Complete Installation Example

Source: https://github.com/educlopez/thegridcn-ui/blob/main/docs/install.md

A comprehensive example demonstrating the installation of a theme, button, and data card, followed by their usage in a React component.

```bash
# 1. init shadcn if you haven't
npx shadcn@latest init

# 2. register the namespace in components.json
#    "registries": { "@thegridcn": "https://thegridcn.com/r/{name}.json" }

# 3. install everything in one shot
npx shadcn@latest add @thegridcn/theme-ares @thegridcn/button @thegridcn/data-card
```

--------------------------------

### Local Development Setup

Source: https://github.com/educlopez/thegridcn-ui/blob/main/CONTRIBUTING.md

Clone the repository, install dependencies, and start the development server. Ensure Node 20+ and pnpm 9+ are installed.

```bash
git clone https://github.com/educlopez/thegridcn-ui.git
cd thegridcn-ui
pnpm install
pnpm dev
```

--------------------------------

### Install and Run Development Server

Source: https://github.com/educlopez/thegridcn-ui/blob/main/README.md

Installs project dependencies using pnpm and starts the development server. Ensure Node.js 18+ and pnpm are installed.

```bash
pnpm install
pnpm dev          # http://localhost:3000
```

--------------------------------

### Start Production Server

Source: https://github.com/educlopez/thegridcn-ui/blob/main/_autodocs/configuration.md

Run `pnpm start` to launch the production server after a successful build.

```bash
pnpm start
```

--------------------------------

### Install Component from Local URL

Source: https://github.com/educlopez/thegridcn-ui/blob/main/src/registry/README.md

Use this command to install a component directly from a local registry URL.

```bash
npx shadcn@latest add http://localhost:3000/r/button.json
```

--------------------------------

### Install Multiple Components

Source: https://github.com/educlopez/thegridcn-ui/blob/main/docs/install.md

Install several components from The GridCN namespace simultaneously to streamline your workflow.

```bash
npx shadcn@latest add @thegridcn/button @thegridcn/data-card @thegridcn/hud
```

--------------------------------

### Install Component from Published Registry URL

Source: https://github.com/educlopez/thegridcn-ui/blob/main/src/registry/README.md

Install a component from a deployed registry by providing its public URL.

```bash
npx shadcn@latest add https://your-domain.com/r/button.json
```

--------------------------------

### Install Components via shadcn CLI

Source: https://github.com/educlopez/thegridcn-ui/blob/main/_autodocs/README.md

Install components using the shadcn CLI after registering the namespace.

```bash
npx shadcn@latest add @thegridcn/button
npx shadcn@latest add @thegridcn/data-card
npx shadcn@latest add @thegridcn/theme-ares
```

--------------------------------

### Install Component using Local Registry File

Source: https://github.com/educlopez/thegridcn-ui/blob/main/src/registry/README.md

Install a component by referencing the local registry file and component name.

```bash
npx shadcn@latest add --registry ./registry.json button
```

--------------------------------

### Install The GridCN Button Component

Source: https://github.com/educlopez/thegridcn-ui/blob/main/docs/install.md

Install the button component from The GridCN namespace using the shadcn CLI.

```bash
npx shadcn@latest add @thegridcn/button
```

--------------------------------

### Render Installed Components

Source: https://github.com/educlopez/thegridcn-ui/blob/main/docs/install.md

Example React component demonstrating how to use the installed Button and DataCard components from The GridCN UI.

```tsx
// app/page.tsx
import { Button } from "@/components/ui/button";
import { DataCard } from "@/components/thegridcn/data-card";

export default function Page() {
  return (
    <div className="min-h-screen bg-background p-8">
      <DataCard
        subtitle="PROGRAM"
        title="FLYNN"
        status="active"
        fields={[
          { label: "STATUS", value: "ACTIVE" },
          { label: "TYPE", value: "USER" },
        ]} />
      <Button className="mt-6">Enter the Grid</Button>
    </div>
  );
}
```

--------------------------------

### Install The GridCN Theme

Source: https://github.com/educlopez/thegridcn-ui/blob/main/docs/install.md

Install a theme from The GridCN namespace. Themes provide pre-defined styles and CSS variables.

```bash
npx shadcn@latest add @thegridcn/theme-ares
npx shadcn@latest add @thegridcn/theme-tron
npx shadcn@latest add @thegridcn/theme-clu
npx shadcn@latest add @thegridcn/theme-athena
npx shadcn@latest add @thegridcn/theme-aphrodite
npx shadcn@latest add @thegridcn/theme-poseidon
```

--------------------------------

### Production Build and Start Commands

Source: https://github.com/educlopez/thegridcn-ui/blob/main/_autodocs/INDEX.md

Commands to build the project for production and start the production server. Also includes a command to regenerate theme tokens.

```bash
pnpm build    # Builds registry + Next.js
pnpm start    # Runs production server
pnpm tokens:build  # Regenerate theme tokens
```

--------------------------------

### Install Component by Full URL

Source: https://github.com/educlopez/thegridcn-ui/blob/main/docs/install.md

Install a component directly using its full URL without needing to register the namespace in `components.json`.

```bash
npx shadcn@latest add https://thegridcn.com/r/button.json
npx shadcn@latest add https://thegridcn.com/r/data-card.json
```

--------------------------------

### Start Development Server

Source: https://github.com/educlopez/thegridcn-ui/blob/main/_autodocs/configuration.md

Run the `pnpm dev` command to start the Next.js development server. This enables hot reloading and TypeScript checking.

```bash
pnpm dev
```

--------------------------------

### Install Tron-Flavored Components

Source: https://github.com/educlopez/thegridcn-ui/blob/main/docs/install.md

Install specific Tron-flavored components like data-card and radar from The GridCN namespace.

```bash
npx shadcn@latest add @thegridcn/data-card
npx shadcn@latest add @thegridcn/radar
npx shadcn@latest add @thegridcn/hud
```

--------------------------------

### Install TheGridCN Components via shadcn Registry

Source: https://github.com/educlopez/thegridcn-ui/blob/main/_autodocs/INDEX.md

Installs TheGridCN components using the shadcn CLI. Ensure your `components.json` is configured with the `@thegridcn` registry.

```bash
# Register namespace once
# In components.json:
{
  "registries": {
    "@thegridcn": "https://thegridcn.com/r/{name}.json"
  }
}

# Then install components
npx shadcn@latest add @thegridcn/button
npx shadcn@latest add @thegridcn/data-card
npx shadcn@latest add @thegridcn/theme-ares
```

--------------------------------

### SearchInput Example

Source: https://github.com/educlopez/thegridcn-ui/blob/main/_autodocs/api-reference/form-input-components.md

Example of using the SearchInput component for searching components. Includes debounce and a search handler.

```tsx
import { SearchInput } from "@/components/thegridcn"
import { useState } from "react"

export function ComponentSearch() {
  const [query, setQuery] = useState("")
  const [results, setResults] = useState([])
  
  const handleSearch = async (q: string) => {
    const res = await fetch(`/api/search?q=${q}`)
    setResults(await res.json())
  }
  
  return (
    <SearchInput
      placeholder="SEARCH COMPONENTS"
      value={query}
      onChange={setQuery}
      onSearch={handleSearch}
      debounce={500}
    />
  )
}
```

--------------------------------

### LoginTemplate Example

Source: https://github.com/educlopez/thegridcn-ui/blob/main/_autodocs/api-reference/templates-utilities.md

Demonstrates how to use the LoginTemplate component, including handling the login submission.

```tsx
import { LoginTemplate } from "@/components/thegridcn"

export function LoginPage() {
  const handleLogin = async (credentials: { email: string; password: string }) => {
    const res = await fetch("/api/auth/login", {
      method: "POST",
      body: JSON.stringify(credentials),
    })
    // Handle response
  }
  
  return (
    <LoginTemplate
      title="SYSTEM LOGIN"
      onSubmit={handleLogin}
      showSignup={true}
    />
  )
}
```

--------------------------------

### BlogTemplate Example

Source: https://github.com/educlopez/thegridcn-ui/blob/main/_autodocs/api-reference/templates-utilities.md

Shows how to implement the BlogTemplate with an array of articles and an article selection handler.

```tsx
import { BlogTemplate } from "@/components/thegridcn"

interface BlogArticle {
  id: string
  title: string
  excerpt: string
  author: string
  date: string
  readTime: number
  category: string
  featured: boolean
}

export function BlogPage() {
  const articles: BlogArticle[] = [
    {
      id: "1",
      title: "The Future of UI",
      excerpt: "Exploring next-generation interfaces...",
      author: "CLU",
      date: "2024-01-15",
      readTime: 5,
      category: "Design",
      featured: true,
    },
  ]
  
  return (
    <BlogTemplate
      articles={articles}
      onArticleSelect={(id) => console.log(`Reading ${id}`)}
    />
  )
}
```

--------------------------------

### Install 3D Grid Component

Source: https://github.com/educlopez/thegridcn-ui/blob/main/docs/install.md

Install the 3D grid component, which automatically includes necessary dependencies like three.js and @react-three/fiber.

```bash
npx shadcn@latest add @thegridcn/grid
```

--------------------------------

### Install The GridCN Components via CLI

Source: https://github.com/educlopez/thegridcn-ui/blob/main/README.md

Use the shadcn CLI to add individual components or multiple components at once. Ensure you have registered the namespace in your components.json first.

```bash
npx shadcn@latest add @thegridcn/button
npx shadcn@latest add @thegridcn/data-card
npx shadcn@latest add @thegridcn/theme-ares

# or several at once
npx shadcn@latest add @thegridcn/button @thegridcn/hud @thegridcn/radar
```

--------------------------------

### LandingTemplate Customization Example

Source: https://github.com/educlopez/thegridcn-ui/blob/main/_autodocs/api-reference/templates-utilities.md

Provides an example of how to customize the LandingTemplate with specific titles, subtitles, CTA text, and feature items.

```tsx
import { LandingTemplate } from "@/components/thegridcn"

export function CustomLanding() {
  return (
    <LandingTemplate
      title="My Amazing Product"
      subtitle="Powered by The GridCN"
      ctaText="Start Free"
      features={[
        { title: "Fast", description: "Optimized performance" },
        { title: "Secure", description: "Enterprise security" },
      ]}
    />
  )
}
```

--------------------------------

### Theme Provider Setup in Layout

Source: https://github.com/educlopez/thegridcn-ui/blob/main/_autodocs/configuration.md

Configures the ThemeProvider and initializes theme/intensity from localStorage before hydration.

```tsx
// app/layout.tsx
import { ThemeProvider } from "@/components/theme"

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en" suppressHydrationWarning>
      <head>
        <script
          dangerouslySetInnerHTML={{
            __html: `
              (function() {
                const theme = localStorage.getItem('project-ares-theme') || 'tron';
                document.documentElement.setAttribute('data-theme', theme);
                const intensity = localStorage.getItem('project-ares-theme-intensity') || 'medium';
                if (intensity !== 'none') {
                  document.documentElement.setAttribute('data-tron-intensity', intensity);
                }
              })()
            `,
          }}
        />
      </head>
      <body>
        <ThemeProvider>
          {children}
        </ThemeProvider>
      </body>
    </html>
  )
}
```

--------------------------------

### GET /api/registry/index.json

Source: https://github.com/educlopez/thegridcn-ui/blob/main/_autodocs/endpoints.md

Retrieve a manifest of all available components in the registry.

```APIDOC
## GET /api/registry/index.json

### Description
Manifest of all available components in the registry.

### Method
GET

### Endpoint
/api/registry/index.json

### Response
#### Success Response (200)
- **version** (string) - Description
- **components** (array) - Description
  - **name** (string) - Description
  - **registryDependencies** (array) - Description
  - **files** (array) - Description
    - **path** (string) - Description
    - **type** (string) - Description

#### Response Example
```json
{
  "version": "1.0.0",
  "components": [
    {
      "name": "button",
      "registryDependencies": ["@radix-ui/react-slot"],
      "files": [
        {
          "path": "src/components/ui/button.tsx",
          "type": "registry:component"
        }
      ]
    },
    {
      "name": "data-card",
      "registryDependencies": [],
      "files": [
        {
          "path": "src/components/thegridcn/data-card.tsx",
          "type": "registry:component"
        }
      ]
    }
  ]
}
```
```

--------------------------------

### NumberInput Example

Source: https://github.com/educlopez/thegridcn-ui/blob/main/_autodocs/api-reference/form-input-components.md

Example of using the NumberInput component to select game difficulty. Sets min, max, and step values.

```tsx
import { NumberInput } from "@/components/thegridcn"
import { useState } from "react"

export function GameDifficultySelector() {
  const [difficulty, setDifficulty] = useState(5)
  
  return (
    <NumberInput
      label="DIFFICULTY"
      value={difficulty}
      onChange={setDifficulty}
      min={1}
      max={10}
      step={1}
    />
  )
}
```

--------------------------------

### Local Development Commands

Source: https://github.com/educlopez/thegridcn-ui/blob/main/_autodocs/README.md

Commands for local development, including installation, running the dev server, building, and linting.

```bash
pnpm install
pnpm dev      # http://localhost:3000
pnpm build    # Production build
pnpm lint     # ESLint checks
```

--------------------------------

### Install Components with shadcn CLI

Source: https://github.com/educlopez/thegridcn-ui/blob/main/_autodocs/configuration.md

Configure your project's `components.json` to register custom component registries. Then, use the shadcn CLI to add components from the specified registries.

```json
{
  "style": "default",
  "rsc": true,
  "tsx": true,
  "aliases": {
    "@/components": "./src/components",
    "@/lib": "./src/lib"
  },
  "registries": {
    "@thegridcn": "https://thegridcn.com/r/{name}.json"
  }
}
```

```bash
npx shadcn@latest add @thegridcn/button
npx shadcn@latest add @thegridcn/data-card
npx shadcn@latest add @thegridcn/theme-ares
```

--------------------------------

### AnalyticsTemplate Example

Source: https://github.com/educlopez/thegridcn-ui/blob/main/_autodocs/api-reference/templates-utilities.md

Illustrates the usage of AnalyticsTemplate, passing in metric data and a date range change handler.

```tsx
import { AnalyticsTemplate } from "@/components/thegridcn"

interface Metric {
  label: string
  value: number
  change: number // percentage
  unit: string
}

export function AnalyticsDashboard() {
  const metrics: Metric[] = [
    { label: "Users", value: 12450, change: 5.2, unit: "" },
    { label: "Revenue", value: 48230, change: 12.1, unit: "$" },
  ]
  
  return (
    <AnalyticsTemplate
      metrics={metrics}
      onDateRangeChange={(start, end) => {
        // Fetch data for date range
      }}
    />
  )
}
```

--------------------------------

### Get All Registered Components

Source: https://github.com/educlopez/thegridcn-ui/blob/main/src/registry/README.md

Retrieve all components currently registered in the system.

```typescript
import {
  getRegistryEntry,
  getAllRegistryEntries,
  getRegistryDependencies
} from "@/registry"

// Get all registered components
const allComponents = getAllRegistryEntries()
```

--------------------------------

### Grid3D Component Example

Source: https://github.com/educlopez/thegridcn-ui/blob/main/_autodocs/api-reference/3d-effects.md

Dynamically import and render the Grid3D component for a 3D grid floor scene. Ensure SSR is disabled for this component.

```tsx
import dynamic from "next/dynamic"
import { Grid3D } from "@/components/thegridcn"

// SSR-safe dynamic import
const Scene = dynamic(
  () => import("@/components/thegridcn").then(m => ({ default: m.Grid3D })),
  { ssr: false }
)

export function HeroScene() {
  return (
    <div className="relative h-96 w-full overflow-hidden rounded-lg">
      <Grid3D
        className="h-full w-full"
        enableParticles={true}
        enableBeams={true}
        cameraAnimation={true}
      />
    </div>
  )
}
```

--------------------------------

### Import Theme CSS

Source: https://github.com/educlopez/thegridcn-ui/blob/main/docs/install.md

Import the installed theme's CSS file into your global CSS to apply the styles across your application.

```css
/* src/app/globals.css */
@import "tailwindcss";
@import "../styles/thegridcn-theme.css";
```

--------------------------------

### Theme Switching Component

Source: https://github.com/educlopez/thegridcn-ui/blob/main/_autodocs/README.md

Implement a client component to toggle between themes. This example switches between 'ares' and 'tron' themes.

```tsx
"use client"
import { useTheme } from "@/components/theme"

export function ThemeToggle() {
  const { theme, setTheme } = useTheme()
  return (
    <button onClick={() => setTheme(theme === "ares" ? "tron" : "ares")}>
      Switch theme
    </button>
  )
}
```

--------------------------------

### Code Splitting Templates

Source: https://github.com/educlopez/thegridcn-ui/blob/main/_autodocs/api-reference/templates-utilities.md

Provides an example of how to implement code splitting for template components using dynamic imports. This is a performance optimization technique for large pages to reduce initial bundle size.

```tsx
const DashboardTemplate = dynamic(
  () => import("@/components/thegridcn").then(m => ({ default: m.DashboardTemplate })),
  { loading: () => <LoadingSpinner /> }
)
```

--------------------------------

### Theme Setup in Next.js Layout

Source: https://github.com/educlopez/thegridcn-ui/blob/main/_autodocs/README.md

Set up the ThemeProvider in your Next.js app layout to enable theme functionality. Ensure to use the 'ares' theme as a default.

```tsx
// app/layout.tsx
import { ThemeProvider } from "@/components/theme"

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en" suppressHydrationWarning>
      <body>
        <ThemeProvider defaultTheme="ares">
          {children}
        </ThemeProvider>
      </body>
    </html>
  )
}
```

--------------------------------

### DashboardTemplate

Source: https://github.com/educlopez/thegridcn-ui/blob/main/_autodocs/api-reference/templates-utilities.md

Complete pre-built dashboard with header, sidebar, and example content. It includes an animated header, sidebar with menu items, data cards, a status bar, and a responsive layout.

```APIDOC
## DashboardTemplate

### Description
Complete pre-built dashboard with header, sidebar, and example content. It includes an animated header, sidebar with menu items, data cards, a status bar, and a responsive layout.

### Signature
```tsx
function DashboardTemplate(props?: DashboardTemplateProps): React.ReactElement
```

### Props
#### Parameters
- **customContent** (React.ReactNode) - Optional - Override main content
- **showSidebar** (boolean) - Optional - Display sidebar (default: true)
- **className** (string) - Optional - Additional CSS classes

### Returns
Complete dashboard page with Tron styling.

### Features Included
- Animated header with navigation
- Sidebar with menu items
- Grid of stat/data cards
- Status bar
- Responsive layout
- Theme-aware colors

### Example
```tsx
import { DashboardTemplate } from "@/components/thegridcn"

// Simple usage (renders with example content)
export function MyDashboard() {
  return <DashboardTemplate />
}

// Custom content
export function CustomDashboard() {
  return (
    <DashboardTemplate
      customContent={
        <div>
          <h1>Custom Dashboard</h1>
          {/* Your metrics */}
        </div>
      }
    />
  )
}
```
```

--------------------------------

### Intensity CSS Variables Example

Source: https://github.com/educlopez/thegridcn-ui/blob/main/_autodocs/theme-system.md

Shows how intensity levels define CSS variables for glow opacity, animation duration, and border width.

```css
[data-tron-intensity="heavy"] {
  --glow-opacity: 0.8;
  --animation-duration: 0.5s;
  --border-width: 2px;
}
```

--------------------------------

### DataCard Example

Source: https://github.com/educlopez/thegridcn-ui/blob/main/_autodocs/api-reference/core-components.md

Use DataCard to display system status, metrics, and information panels with a Tron-inspired design. It supports custom fields, highlight effects, and status indicators.

```tsx
import { DataCard } from "@/components/thegridcn"

export function SystemMonitor() {
  return (
    <DataCard
      title="SYSTEM CORE"
      subtitle="DIAGNOSTIC_PANEL_02"
      status="active"
      fields={[
        { label: "CPU", value: "87%", highlight: true },
        { label: "MEMORY", value: "3.2GB / 8GB" },
        { label: "NETWORK", value: "45Mbps ↓ / 12Mbps ↑" },
        { label: "UPTIME", value: "287:45:32" },
      ]}
      className="w-full max-w-md"
    />
  )
}
```

--------------------------------

### GET /api/registry/[component]

Source: https://github.com/educlopez/thegridcn-ui/blob/main/_autodocs/endpoints.md

Fetches a component from the shadcn-compatible registry. Supports theme-specific styling and intensity levels. Can also retrieve CSS styles for a given theme and intensity.

```APIDOC
## GET /api/registry/[component]

### Description
Fetch a component from the shadcn-compatible registry with theme-specific styling. When the component is "styles", it returns CSS-only registry entry.

### Method
GET

### Endpoint
/api/registry/[component]

### Parameters
#### Query Parameters
- **theme** (string) - Optional - Theme for styling. Valid values: "tron", "ares", "clu", "athena", "aphrodite", "poseidon". Defaults to "tron".
- **intensity** (string) - Optional - Intensity level for styling. Valid values: "none", "light", "medium", "heavy". Defaults to "medium".

### Response
#### Success Response (200)
- **$schema** (string) - Schema URL for the registry item.
- **name** (string) - The name of the component or style.
- **title** (string) - The display title of the component or style.
- **description** (string) - A description of the component.
- **type** (string) - The type of registry item (e.g., "registry:component", "registry:style").
- **files** (array) - An array of files associated with the registry item, including component code and CSS.
  - **path** (string) - The path to the file.
  - **content** (string) - The content of the file.
  - **type** (string) - The type of the file.
- **dependencies** (array) - An array of dependencies for the component.

#### Response Example (Component)
```json
{
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
  "name": "component-name",
  "title": "Component Title",
  "description": "Component description",
  "type": "registry:component",
  "files": [
    {
      "path": "src/components/ui/component-name.tsx",
      "content": "// component code",
      "type": "registry:component"
    },
    {
      "path": "src/styles/thegridcn.css",
      "content": "/* CSS for theme */",
      "type": "registry:style"
    }
  ],
  "dependencies": ["@radix-ui/react-dialog"]
}
```

#### Response Example (Styles Only)
```json
{
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
  "name": "thegridcn-styles-tron-medium",
  "title": "TheGridcn Styles (tron, medium)",
  "type": "registry:style",
  "files": [
    {
      "path": "src/styles/thegridcn.css",
      "content": "/* combined CSS for theme + intensity */",
      "type": "registry:style"
    }
  ]
}
```

#### Error Handling
- **404 Not Found**: Component not found.
- **400 Bad Request**: Invalid theme or intensity provided.
```

--------------------------------

### Using DataCard Component

Source: https://github.com/educlopez/thegridcn-ui/blob/main/_autodocs/README.md

Example of how to use the DataCard component to display system status information. It includes title, subtitle, status, and a list of fields with labels and values.

```tsx
import { DataCard } from "@/components/thegridcn"

export function MyDataCard() {
  return (
    <DataCard
      title="System Status"
      subtitle="CORE_MONITOR"
      status="active"
      fields={[
        { label: "CPU", value: "94%", highlight: true },
        { label: "Memory", value: "2.4GB" },
        { label: "Uptime", value: "42h 17m" },
      ]}
    />
  )
}
```

--------------------------------

### Code Splitting for Routes and Components

Source: https://github.com/educlopez/thegridcn-ui/blob/main/_autodocs/utilities.md

Provides examples of code splitting strategies, including route-based splitting for pages and component-based splitting for modals, utilizing dynamic imports.

```tsx
// Route-based code splitting
const DashboardPage = dynamic(() => import("./dashboard"))

// Component-based code splitting  
const Modal = dynamic(() => import("./modal"), { ssr: false })
```

--------------------------------

### Initialize shadcn CLI

Source: https://github.com/educlopez/thegridcn-ui/blob/main/docs/install.md

Run this command to initialize the shadcn CLI in your project if you don't have a `components.json` file.

```bash
npx shadcn@latest init
```

--------------------------------

### TextInput Example

Source: https://github.com/educlopez/thegridcn-ui/blob/main/_autodocs/api-reference/form-input-components.md

Example of using the TextInput component for a login form. Handles state for username and error messages.

```tsx
import { TextInput } from "@/components/thegridcn"
import { useState } from "react"

export function LoginForm() {
  const [username, setUsername] = useState("")
  const [error, setError] = useState("")
  
  const handleSubmit = () => {
    if (!username) {
      setError("Username required")
      return
    }
    // Submit logic
  }
  
  return (
    <form onSubmit={handleSubmit}>
      <TextInput
        label="USERNAME"
        placeholder="user_001"
        value={username}
        onChange={setUsername}
        error={error}
      />
    </form>
  )
}
```

--------------------------------

### Conventional Commits Examples

Source: https://github.com/educlopez/thegridcn-ui/blob/main/CONTRIBUTING.md

Examples of commit messages following the Conventional Commits specification for various types of changes.

```git
feat: add radar sweep component
fix: resolve theme flash on first paint
docs: update install guide with tokens example
```

--------------------------------

### List Available Components from GitHub

Source: https://github.com/educlopez/thegridcn-ui/blob/main/docs/install.md

Enumerate component names directly from the GitHub repository using `curl`, `jq`, and the `registry.json` file.

```bash
curl -sL https://raw.githubusercontent.com/educlopez/thegridcn-ui/main/registry.json | jq -r '.items[].name' | sort -u
```

--------------------------------

### Build for Production

Source: https://github.com/educlopez/thegridcn-ui/blob/main/_autodocs/configuration.md

Execute `pnpm build` to first generate the shadcn registry and then build the Next.js application for production.

```bash
pnpm build
```

--------------------------------

### List Available Components Locally

Source: https://github.com/educlopez/thegridcn-ui/blob/main/docs/install.md

Enumerate component names from a local clone of thegridcn-ui repository using `jq` and `registry.json`.

```bash
# from a clone of thegridcn-ui
jq -r '.items[].name' registry.json | sort -u
```

--------------------------------

### Development Commands

Source: https://github.com/educlopez/thegridcn-ui/blob/main/_autodocs/INDEX.md

Basic commands for setting up and running the project in development mode. Uses pnpm package manager.

```bash
pnpm install
pnpm dev      # http://localhost:3000
pnpm lint     # Check for issues
```

--------------------------------

### GET /api/leaderboard/session

Source: https://github.com/educlopez/thegridcn-ui/blob/main/_autodocs/endpoints.md

Create a new game session token for leaderboard submissions.

```APIDOC
## GET /api/leaderboard/session

### Description
Create a new game session token.

### Method
GET

### Endpoint
/api/leaderboard/session

### Response
#### Success Response (200)
- **token** (string) - HMAC-signed session token for leaderboard submission
- **expiresIn** (number) - Session TTL in seconds (1800 = 30 minutes)

#### Response Example
```json
{
  "token": "uuid.hmac-signature",
  "expiresIn": 1800
}
```
```

--------------------------------

### Build Component Registry

Source: https://github.com/educlopez/thegridcn-ui/blob/main/CONTRIBUTING.md

After adding a new component and registering it in `registry.json`, run this command to build the component registry.

```bash
pnpm registry:build
```

--------------------------------

### Get Component Dependency Tree

Source: https://github.com/educlopez/thegridcn-ui/blob/main/src/registry/README.md

Retrieve all transitive dependencies for a specified component.

```typescript
import {
  getComponentMetadata,
  getAllComponents,
  getComponentDependencies,
  isComponentRegistered,
  getComponentsThatDependOn,
  getDependencyTree,
  getComponentsInDependencyOrder
} from "@/registry/utils"

// Get dependency tree (all transitive dependencies)
const tree = getDependencyTree("alert-dialog")
// Returns: ["button"]
```

--------------------------------

### Get Component Dependencies

Source: https://github.com/educlopez/thegridcn-ui/blob/main/src/registry/README.md

Retrieve the list of registry dependencies for a given component.

```typescript
import {
  getRegistryEntry,
  getAllRegistryEntries,
  getRegistryDependencies
} from "@/registry"

// Get component dependencies
const deps = getRegistryDependencies("alert-dialog")
// Returns: ["button"]
```

--------------------------------

### Search and List Components

Source: https://github.com/educlopez/thegridcn-ui/blob/main/docs/install.md

Use these commands to search for components within The GridCN registry or list all available components.

```bash
npx shadcn@latest search @thegridcn
npx shadcn@latest search @thegridcn --query "hud"
npx shadcn@latest list   @thegridcn
```

--------------------------------

### Development and Build Commands

Source: https://github.com/educlopez/thegridcn-ui/blob/main/CLAUDE.md

Common commands for managing the development server, building for production, running the production server, and performing lint checks using pnpm.

```bash
pnpm dev      # Start development server (port 3000)
pnpm build    # Build for production
pnpm start    # Run production server
pnpm lint     # Run ESLint checks
```

--------------------------------

### Get Template Source

Source: https://github.com/educlopez/thegridcn-ui/blob/main/_autodocs/INDEX.md

Retrieves the source code for a specific template identified by its slug.

```APIDOC
## GET /api/template-source/[slug]

### Description
Fetches the source code of a template identified by its slug.

### Method
GET

### Endpoint
`/api/template-source/[slug]`

### Parameters
#### Path Parameters
- **slug** (string) - Required - The unique identifier (slug) of the template.

### Response
#### Success Response (200)
- The source code of the requested template.
```

--------------------------------

### Verify Individual Component

Source: https://github.com/educlopez/thegridcn-ui/blob/main/src/registry/PRODUCTION.md

Use this command to test if a specific component's registry JSON file is being served correctly in production.

```bash
# Test individual component
curl https://your-domain.com/r/button.json

# Should return the component JSON
```

--------------------------------

### Get Leaderboard Entries

Source: https://github.com/educlopez/thegridcn-ui/blob/main/_autodocs/INDEX.md

Retrieves leaderboard entries. Allows filtering by difficulty level.

```APIDOC
## GET /api/leaderboard?difficulty=medium

### Description
Gets leaderboard entries, optionally filtered by difficulty.

### Method
GET

### Endpoint
`/api/leaderboard`

### Parameters
#### Query Parameters
- **difficulty** (string) - Optional - The difficulty level to filter by (e.g., 'easy', 'medium', 'hard', 'insane').

### Response
#### Success Response (200)
- An array of leaderboard entries, each containing score and player information.
```

--------------------------------

### Build Theme Tokens

Source: https://github.com/educlopez/thegridcn-ui/blob/main/CONTRIBUTING.md

After adding a new theme to `globals.css` and exporting it, run this command to regenerate theme CSS and JSON files.

```bash
pnpm tokens:build
```

--------------------------------

### Get Specific Component Registry Entry

Source: https://github.com/educlopez/thegridcn-ui/blob/main/src/registry/README.md

Retrieve the registry entry for a particular component by its name.

```typescript
import {
  getRegistryEntry,
  getAllRegistryEntries,
  getRegistryDependencies
} from "@/registry"

// Get a specific component's registry entry
const buttonEntry = getRegistryEntry("button")
```

--------------------------------

### Generate Static Files and Build App

Source: https://github.com/educlopez/thegridcn-ui/blob/main/src/registry/PRODUCTION.md

This sequence of commands ensures that static registry files are generated and then the Next.js application is built, optimizing for performance and CDN caching.

```bash
pnpm registry:build  # Generate static files
pnpm build          # Build Next.js app (includes registry:build automatically)
```

--------------------------------

### Initialize ThemeProvider in Layout

Source: https://github.com/educlopez/thegridcn-ui/blob/main/README.md

Wrap your application's root layout with the ThemeProvider to enable theme switching. Set a default theme using the 'defaultTheme' prop.

```tsx
// app/layout.tsx
import { ThemeProvider } from "@/components/theme";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en" suppressHydrationWarning>
      <body>
        <ThemeProvider defaultTheme="ares">{children}</ThemeProvider>
      </body>
    </html>
  );
}
```

--------------------------------

### GET /api/og/[theme]

Source: https://github.com/educlopez/thegridcn-ui/blob/main/_autodocs/endpoints.md

Generate an open graph image preview for social sharing with a specified theme.

```APIDOC
## GET /api/og/[theme]

### Description
Generate an open graph image preview for social sharing.

### Method
GET

### Endpoint
/api/og/[theme]

### Parameters
#### Path Parameters
- **theme** (string) - Required - One of: "ares", "tron", "clu", "athena", "aphrodite", "poseidon"

### Response
Returns a PNG image (1200x630px) with the theme's color scheme and branding.
```

--------------------------------

### Get Components in Dependency Order

Source: https://github.com/educlopez/thegridcn-ui/blob/main/src/registry/README.md

Retrieve a list of all components, ordered with dependencies appearing before the components that rely on them.

```typescript
import {
  getComponentMetadata,
  getAllComponents,
  getComponentDependencies,
  isComponentRegistered,
  getComponentsThatDependOn,
  getDependencyTree,
  getComponentsInDependencyOrder
} from "@/registry/utils"

// Get components in dependency order (dependencies first)
const ordered = getComponentsInDependencyOrder()
```

--------------------------------

### Add shadcn/ui Components

Source: https://github.com/educlopez/thegridcn-ui/blob/main/_autodocs/endpoints.md

Use these commands to add components from the shadcn/ui registry to your project. This integrates UI components compatible with shadcn's tooling.

```bash
npx shadcn@latest add @thegridcn/button
npx shadcn@latest add @thegridcn/data-card
```

--------------------------------

### Build and Lint Project

Source: https://github.com/educlopez/thegridcn-ui/blob/main/README.md

Commands for building the production version of the project and running ESLint for code quality checks.

```bash
pnpm build        # production build (runs registry:build first)
pnpm lint         # eslint
```

--------------------------------

### DashboardTemplate Simple Usage

Source: https://github.com/educlopez/thegridcn-ui/blob/main/_autodocs/api-reference/templates-utilities.md

Shows the basic usage of the DashboardTemplate component, which renders a complete dashboard with example content.

```tsx
import { DashboardTemplate } from "@/components/thegridcn"

// Simple usage (renders with example content)
export function MyDashboard() {
  return <DashboardTemplate />
}
```

--------------------------------

### GET /api/leaderboard

Source: https://github.com/educlopez/thegridcn-ui/blob/main/_autodocs/endpoints.md

Fetches top leaderboard entries for a specific game difficulty. If no difficulty is specified, it defaults to 'medium'.

```APIDOC
## GET /api/leaderboard

### Description
Fetch top leaderboard entries for a specific difficulty. Returns up to 10 entries with the lowest times.

### Method
GET

### Endpoint
/api/leaderboard

### Parameters
#### Query Parameters
- **difficulty** (string) - Optional - Game difficulty. Valid values: "easy", "medium", "hard", "insane". Defaults to "medium".

### Response
#### Success Response (200)
- **entries** (array) - An array of leaderboard entries.
  - **alias** (string) - The alias of the player.
  - **time** (number) - The time taken in milliseconds.
  - **difficulty** (string) - The difficulty of the game.
  - **date** (string) - The date and time the entry was recorded.
  - **character** (string) - The character used by the player (optional).

#### Response Example
```json
{
  "entries": [
    {
      "alias": "EDU",
      "time": 24.567,
      "difficulty": "medium",
      "date": "2024-01-15T10:30:00Z",
      "character": "User"
    },
    {
      "alias": "CLU",
      "time": 25.123,
      "difficulty": "medium",
      "date": "2024-01-15T09:15:00Z"
    }
  ]
}
```

#### Response Example (No Redis Configured)
```json
{
  "entries": []
}
```
```

--------------------------------

### Build Registry JSON Files with Custom Output

Source: https://github.com/educlopez/thegridcn-ui/blob/main/src/registry/README.md

Specify a custom output directory for the generated individual registry JSON files using the --output flag.

```bash
pnpm registry:build --output public/registry
```

--------------------------------

### Project Package.json Configuration

Source: https://github.com/educlopez/thegridcn-ui/blob/main/_autodocs/configuration.md

Defines project metadata, package manager, and build/development scripts.

```json
{
  "name": "project-ares",
  "version": "0.1.0",
  "packageManager": "pnpm@11.1.2",
  "scripts": {
    "dev": "next dev",
    "build": "pnpm registry:build && next build",
    "start": "next start",
    "lint": "eslint",
    "registry:update": "tsx scripts/update-registry.ts",
    "registry:build": "shadcn build && tsx scripts/enhance-registry-files.ts && tsx scripts/build-registry-styles.ts",
    "tokens:build": "node scripts/export-tokens.mjs"
  }
}
```

--------------------------------

### Tunnel Component Example

Source: https://github.com/educlopez/thegridcn-ui/blob/main/_autodocs/api-reference/3d-effects.md

Dynamically import and render the Tunnel component for a 3D tunnel effect. SSR must be disabled for this component.

```tsx
import dynamic from "next/dynamic"
import { Tunnel } from "@/components/thegridcn"

const TunnelScene = dynamic(
  () => import("@/components/thegridcn").then(m => ({ default: m.Tunnel })),
  { ssr: false }
)

export function DataTransferVisualization() {
  return (
    <div className="h-64 w-full">
      <TunnelScene
        className="h-full"
        speed={0.3}
        depth={30}
        intensity={0.8}
      />
    </div>
  )
}
```

--------------------------------

### InfoPanel Component Example

Source: https://github.com/educlopez/thegridcn-ui/blob/main/_autodocs/api-reference/core-components.md

Displays structured information with a title, subtitle, timestamp, and status. Suitable for system status updates or event logs.

```tsx
import { InfoPanel } from "@/components/thegridcn"

export function ProcessMonitor() {
  return (
    <InfoPanel
      title="SYSTEM_INITIALIZATION"
      subtitle="BOOT_SEQUENCE"
      timestamp="09:45:23"
      status="complete"
    >
      <div className="space-y-2 font-mono text-sm">
        <p>✓ Core systems online</p>
        <p>✓ Memory initialized</p>
        <p>✓ Network connected</p>
      </div>
    </InfoPanel>
  )
}
```

--------------------------------

### Radar Target Positioning Example

Source: https://github.com/educlopez/thegridcn-ui/blob/main/_autodocs/api-reference/core-components.md

Illustrates target coordinate system for the Radar component. Coordinates are percentage-based relative to the radar's center.

```tsx
// Center: (50, 50)
// Top: (50, 0)
// Right: (100, 50)
// Bottom: (50, 100)
// Left: (0, 50)
```

--------------------------------

### Fetch Component from Registry

Source: https://github.com/educlopez/thegridcn-ui/blob/main/_autodocs/INDEX.md

Fetches a specific component from the registry. Supports optional theme and intensity parameters for styling.

```APIDOC
## GET /api/registry/[component]

### Description
Fetches a component from the registry.

### Method
GET

### Endpoint
`/api/registry/[component]`

### Parameters
#### Path Parameters
- **component** (string) - Required - The name of the component to fetch.

#### Query Parameters
- **theme** (string) - Optional - The theme to apply (e.g., 'ares').
- **intensity** (string) - Optional - The visual intensity level (e.g., 'heavy').

### Response
#### Success Response (200)
- Component data and associated styling information.
```

```APIDOC
## GET /api/registry/[component]?theme=ares&intensity=heavy

### Description
Fetches a component from the registry with specified theme and intensity.

### Method
GET

### Endpoint
`/api/registry/[component]`

### Parameters
#### Path Parameters
- **component** (string) - Required - The name of the component to fetch.

#### Query Parameters
- **theme** (string) - Optional - The theme to apply (e.g., 'ares').
- **intensity** (string) - Optional - The visual intensity level (e.g., 'heavy').

### Response
#### Success Response (200)
- Component data with applied theme and intensity styling.
```

--------------------------------

### DashboardLayout Usage Example

Source: https://github.com/educlopez/thegridcn-ui/blob/main/_autodocs/api-reference/templates-utilities.md

Demonstrates how to use the DashboardLayout component to structure a dashboard application. It includes a sidebar, header, and main content area.

```tsx
import { DashboardLayout } from "@/components/thegridcn"

export function Dashboard() {
  return (
    <DashboardLayout
      sidebar={<SidebarNav />}
      header={<TopHeader />}
      className="bg-background"
    >
      <div className="space-y-6">
        <h1>Dashboard</h1>
        <DataCard title="Metrics" fields={[...]} />
      </div>
    </DashboardLayout>
  )
}
```

--------------------------------

### Named Imports from Components and Utilities

Source: https://github.com/educlopez/thegridcn-ui/blob/main/_autodocs/utilities.md

Demonstrates common named import patterns for components and utilities from '@/components' and '@/lib/utils'.

```tsx
// From main index
import { DataCard, Timer, Radar } from "@/components/thegridcn"

// From theme system
import { ThemeProvider, useTheme, selectableThemes } from "@/components/theme"

// From utilities
import { cn, groupComponentsByType } from "@/lib/utils"
```

--------------------------------

### Theme CSS Variables Example

Source: https://github.com/educlopez/thegridcn-ui/blob/main/_autodocs/theme-system.md

Illustrates how theme primary, secondary, and accent colors are defined as CSS variables within a data-theme attribute.

```css
[data-theme="ares"] {
  --primary: oklch(54.5% 0.215 0°);        /* Theme primary color */
  --secondary: oklch(52% 0.15 45°);        /* Secondary color */
  --accent: oklch(80% 0.2 30°);            /* Accent color */
  /* ... additional variables */
}
```

--------------------------------

### Select Component Usage

Source: https://github.com/educlopez/thegridcn-ui/blob/main/_autodocs/api-reference/form-input-components.md

Demonstrates how to use the Select component for theme selection. It includes setting a default value and handling changes.

```tsx
import { Select } from "@/components/thegridcn"
import { useState } from "react"

export function ThemeSelector() {
  const [theme, setTheme] = useState("tron")
  
  return (
    <Select
      label="THEME"
      options={[
        { label: "Tron", value: "tron" },
        { label: "Ares", value: "ares" },
        { label: "Clu", value: "clu" },
        { label: "Athena", value: "athena" },
      ]}
      value={theme}
      onChange={setTheme}
      searchable={true}
    />
  )
}
```

--------------------------------

### Update the Component Registry

Source: https://github.com/educlopez/thegridcn-ui/blob/main/src/registry/README.md

Run this command to scan all components, extract dependencies, update configuration files, and generate registry indexes.

```bash
pnpm registry:update
```