# Array UI (array-ui): Complete LLM & Agent Documentation

> Full specification, design tokens, component APIs, props, and code examples for Array UI (array-ui) hosted at https://ui.arpitbhayani.me.

---

## 1. Identity & Core Design Rules

Array UI is an editorial, systems-engineering design system for personal sites, developer SaaS, and HTML explainer docs. It is designed for engineers and autonomous AI coding agents who value mathematical precision, high information density, and editorial typography.

### Core Visual Principles
1. **Editorial Palette**:
   - Light mode: Paper canvas (`#f9f8f5`), warm hairline borders (`#dfded9` / `rgb(223, 222, 217)`), dark carbon text (`#2b2a30`).
   - Dark mode: Obsidian carbon (`#111113`), crisp border (`#27272c` / `rgb(39, 39, 44)`), soft readable white (`#d6d6dc`).
   - Accents:
     - Signature Crimson (`#e5000f` light, `#ff3344` dark): Reserved strictly for primary action buttons, active navigation indicators, and key focus rings.
     - Amber (`#cc9900`): Used exclusively for engineering maxim quotes and warning callouts.
     - Emerald (`#10b981`): Used for operational health, ping dots, and git diff additions.
     - Rose (`#f43f5e`): Used for errors, outages, and git diff deletions.
2. **Typography**:
   - Headings: Assistant (bold, relaxed tracking -0.015em, aligned with body typography).
   - Body: Assistant (dense, 15px base size).
   - Pull Quotes / Maxims: Lora (italic serif).
   - Code & Telemetry: IBM Plex Mono / system monospace.
3. **Density & Restraint**:
   - 1px hairline borders everywhere.
   - Minimal elevation/shadows; prefer flat, tinted card surfaces.
   - Information-dense layouts: compact margins, dense tables, machined telemetry.
   - Never inject arbitrary gradients, neon colors, or rounded bouncy buttons.

---

## 2. Installation & AI Agent Rules

### Mode A: shadcn CLI Registry (Recommended)
Configure `components.json`:
```json
{
  "$schema": "https://ui.shadcn.com/schema.json",
  "style": "default",
  "registries": {
    "@aui": "https://ui.arpitbhayani.me/r/{name}.json"
  }
}
```

Install base theme:
```bash
npx shadcn@latest add @aui/aui -y
```

Install any components:
```bash
npx shadcn@latest add @aui/button @aui/badge @aui/card @aui/input @aui/terminal @aui/diff-block @aui/property-grid @aui/ping-status -y
```

Components are installed into `@/components/ui/` and imported as:
```tsx
import { Button } from "@/components/ui/button";
import { Badge } from "@/components/ui/badge";
import { Card, CardHeader, CardTitle, CardContent } from "@/components/ui/card";
import { Terminal } from "@/components/ui/terminal";
import { DiffBlock } from "@/components/ui/diff-block";
import { PropertyGrid } from "@/components/ui/property-grid";
import { PingStatus } from "@/components/ui/ping-status";
```

### Mode B: Direct Package Dependency (npm, pnpm, bun)
Install the official package from npm:
```bash
npm install array-ui
# or: pnpm add array-ui / bun add array-ui
```

Setup styles in root layout:
```tsx
import "array-ui/styles.css";
```

Import components:
```tsx
// Next.js (App Router or Pages Router)
import { Button, Badge, Card, Terminal, DiffBlock, PingStatus } from "array-ui/nextjs";

// Astro
import Button from "array-ui/astro/Button.astro";
import Terminal from "array-ui/astro/Terminal.astro";
import DiffBlock from "array-ui/astro/DiffBlock.astro";
import PingStatus from "array-ui/astro/PingStatus.astro";
```

### Autonomous Agent Workflow Rules:
- Autonomously select and install required components (`npx shadcn@latest add @aui/<component> -y`).
- DO NOT pause or ask the user which components to install: immediately implement the requested interface.
- Strictly Maintain 0% Custom CSS: Never write page-level `<style>` blocks or ad-hoc `.css` files. All layout, spacing, and styling MUST be driven exclusively by Array UI components and foundational utility classes.
- Always use `cn()` from `@/lib/utils` for className composition.

---

## 3. Core UI & Action Primitives

### 1. Button (`@aui/button`)
Signature tactile action button with signature crimson primary, secondary, outline, ghost, and destructive variants. Supports optional icons and loading spinner state.
- Endpoint: `https://ui.arpitbhayani.me/r/button.json`
- Props:
  - `variant?: "primary" | "secondary" | "outline" | "ghost" | "destructive" | "link"` (default: "primary")
  - `size?: "default" | "sm" | "lg" | "icon"` (default: "default")
  - `icon?: ReactNode` (optional action/plus/spinner icon)
  - `iconPosition?: "left" | "right"` (default: "left")
  - `leftIcon?: ReactNode`
  - `rightIcon?: ReactNode`
  - `loading?: boolean` (shows animated spinner and disables button)
  - `loadingText?: ReactNode`
  - `asChild?: boolean`
```tsx
<Button variant="primary">Deploy canary</Button>
<Button variant="primary" icon={<PlusIcon />}>New Cluster</Button>
<Button variant="secondary" rightIcon={<ArrowRightIcon />}>Continue</Button>
<Button variant="primary" loading>Deploying...</Button>
<Button variant="secondary" size="icon" icon={<PlusIcon />} />
<Button variant="destructive" size="sm">Terminate</Button>
```

### 2. Badge (`@aui/badge`)
Machined status pill with monospace typography and color variants.
- Endpoint: `https://ui.arpitbhayani.me/r/badge.json`
- Props:
  - `variant?: "default" | "primary" | "secondary" | "outline" | "green" | "amber" | "red" | "blue"`
```tsx
<Badge variant="green">Healthy</Badge>
<Badge variant="amber">Degraded</Badge>
<Badge variant="red">Outage</Badge>
<Badge variant="outline">v0.1.3</Badge>
```

### 3. Card (`@aui/card`)
Flat card surface with 1px hairline border and structured header/content/footer.
- Endpoint: `https://ui.arpitbhayani.me/r/card.json`
- Components: `Card`, `CardHeader`, `CardTitle`, `CardDescription`, `CardContent`, `CardFooter`
```tsx
<Card>
  <CardHeader>
    <CardTitle>Distributed Consensus</CardTitle>
    <CardDescription>Raft state machine replication</CardDescription>
  </CardHeader>
  <CardContent>
    <p className="text-sm text-muted-foreground">Log compaction occurs at 50,000 index increments.</p>
  </CardContent>
  <CardFooter className="justify-between">
    <span className="text-xs font-mono text-muted-foreground">Cluster: us-east-1</span>
    <Button size="sm">Inspect</Button>
  </CardFooter>
</Card>
```

### 4. Input (`@aui/input`)
Machined input with subtle focus ring and optional keyboard shortcut badge.
- Endpoint: `https://ui.arpitbhayani.me/r/input.json`
- Props:
  - `shortcut?: string` (e.g. "⌘K")
  - Standard HTML input props
```tsx
<Input placeholder="Filter clusters..." shortcut="⌘K" />
```

### 5. Kbd (`@aui/kbd`)
Machined monospace keyboard shortcut keycap.
- Endpoint: `https://ui.arpitbhayani.me/r/kbd.json`
- Props:
  - `keys?: string[]`
```tsx
<Kbd keys={["⌘", "K"]} />
<Kbd keys={["Ctrl", "Shift", "P"]} />
```

### 6. Tooltip (`@aui/tooltip`)
Accessible tooltip hint on hover and focus.
- Endpoint: `https://ui.arpitbhayani.me/r/tooltip.json`
- Props:
  - `content: ReactNode`
  - `placement?: "top" | "bottom"`
```tsx
<Tooltip content="Copy commit SHA to clipboard">
  <button className="text-xs font-mono">01hx98z</button>
</Tooltip>
```

### 7. Alert (`@aui/alert`)
Status-tinted inline alert callout.
- Endpoint: `https://ui.arpitbhayani.me/r/alert.json`
- Components: `Alert`, `AlertTitle`, `AlertDescription`
- Props:
  - `variant?: "default" | "info" | "success" | "warning" | "destructive"`
```tsx
<Alert variant="warning">
  <AlertTitle>Replication Lag Detected</AlertTitle>
  <AlertDescription>Replica eu-west-1b is 418ms behind primary ledger.</AlertDescription>
</Alert>
```

### 8. Tabs (`@aui/tabs`)
Underline tab navigation with keyboard accessibility.
- Endpoint: `https://ui.arpitbhayani.me/r/tabs.json`
- Components: `Tabs`, `TabsList`, `TabsTrigger`, `TabsContent`
```tsx
<Tabs defaultValue="telemetry">
  <TabsList>
    <TabsTrigger value="telemetry">Telemetry</TabsTrigger>
    <TabsTrigger value="logs">Logs</TabsTrigger>
  </TabsList>
  <TabsContent value="telemetry">
    <p>Live metrics and throughput</p>
  </TabsContent>
  <TabsContent value="logs">
    <p>Stdout stream</p>
  </TabsContent>
</Tabs>
```

### 9. Accordion (`@aui/accordion`)
Collapsible hairline accordion sections.
- Endpoint: `https://ui.arpitbhayani.me/r/accordion.json`
- Components: `Accordion`, `AccordionItem`, `AccordionTrigger`, `AccordionContent`
```tsx
<Accordion type="single" defaultValue="item-1">
  <AccordionItem value="item-1">
    <AccordionTrigger>How does log compaction work?</AccordionTrigger>
    <AccordionContent>Snapshots discard prefix entries safely.</AccordionContent>
  </AccordionItem>
</Accordion>
```

### 10. Dropdown (`@aui/dropdown`)
Accessible action menu with click-outside dismissal and keyboard escape support.
- Endpoint: `https://ui.arpitbhayani.me/r/dropdown.json`
- Props:
  - `trigger: ReactNode`
  - `children: ReactNode`
  - `align?: "left" | "right"`
```tsx
<Dropdown trigger={<Button variant="secondary" size="sm">Actions ▼</Button>}>
  <div className="aui-dropdown-header">Cluster Options</div>
  <button type="button" className="aui-dropdown-item">Restart Nodes</button>
  <div className="aui-dropdown-divider" />
  <button type="button" className="aui-dropdown-item is-destructive">Drain Node</button>
</Dropdown>
```

### 11. Gutter (`@aui/gutter`)
Component-driven whitespace blank spacing primitive between UI elements (e.g. space between navbar and content). Eliminates ad-hoc external CSS margins and paddings.
- Endpoint: `https://ui.arpitbhayani.me/r/gutter.json`
- Props:
  - `size?: "none" | "2xs" | "xs" | "sm" | "md" | "lg" | "xl" | "2xl" | "3xl" | "4xl" | number | string` (default: "md")
  - `orientation?: "vertical" | "horizontal"` (default: "vertical")
  - `axis?: "x" | "y"` (shorthand: "y" for vertical, "x" for horizontal)
- Alias: `Spacer`
```tsx
// Vertical blank space between navbar and first component
<Navbar brandName="Console" links={links} />
<Gutter size="lg" />
<main>...</main>

// Horizontal whitespace in a flex row
<div className="aui-row">
  <Button>Primary</Button>
  <Gutter orientation="horizontal" size="sm" />
  <Button variant="secondary">Secondary</Button>
</div>
```

---

## 4. Developer & Systems Primitives

### 12. Terminal (`@aui/terminal`)
Machined telemetry terminal with bash command dots and styled outputs.
- Endpoint: `https://ui.arpitbhayani.me/r/terminal.json`
- Props:
  - `title?: string` (e.g. "~/cluster" or "bash")
  - `lines: (string | { text: string; kind?: "cmd" | "out" | "ok" | "err" })[]`
```tsx
<Terminal
  title="~/cluster"
  lines={[
    "kubectl get pods -n prod",
    { text: "pod/api-server-79f9  1/1 Running", kind: "ok" },
    { text: "pod/worker-004       0/1 CrashLoop", kind: "err" },
    { text: "exit code 1", kind: "out" },
  ]}
/>
```

### 13. DiffBlock (`@aui/diff-block`)
Unified git patch inspector with line gutters, additions, and deletions.
- Endpoint: `https://ui.arpitbhayani.me/r/diff-block.json`
- Props:
  - `file?: string`
  - `diff?: string` (unified patch; hunk headers set line numbers)
  - `lines?: DiffLine[]` (alternative to diff; per-line `coverage`, `segments`, `note`)
  - `view?: "unified" | "split"`
  - `collapseContext?: number | false` (fold unchanged lines beyond N around each change)
  - `showCoverage?: boolean` (coverage rail from `coverage: "covered" | "uncovered" | "partial"`)
  - `highlightWords?: boolean` (default true)
```tsx
<DiffBlock
  file="migrations/0042_status.sql"
  diff={`@@ -12,4 +12,4 @@
-status: varchar(32) DEFAULT 'pending',
+status: cluster_status NOT NULL DEFAULT 'provisioning',`}
/>
```

### 14. PingStatus (`@aui/ping-status`)
Pulsing heartbeat indicator with status and latency.
- Endpoint: `https://ui.arpitbhayani.me/r/ping-status.json`
- Props:
  - `status: "operational" | "degraded" | "outage" | "maintenance"`
  - `label?: string`
  - `size?: "sm" | "md" | "lg"`
```tsx
<PingStatus status="operational" label="Operational · 42ms" size="md" />
```

### 15. PropertyGrid (`@aui/property-grid`)
Dense key-value metadata inspector for entities and systems, with one-click copy.
- Endpoint: `https://ui.arpitbhayani.me/r/property-grid.json`
- Props:
  - `items: { label: string; value: string; copyValue?: string }[]`
```tsx
<PropertyGrid
  items={[
    { label: "Cluster ID", value: "cls_01HX98Z", copyValue: "cls_01HX98Z" },
    { label: "Region", value: "eu-west-1 (Ireland)" },
    { label: "VPC CIDR", value: "10.140.0.0/16", copyValue: "10.140.0.0/16" },
  ]}
/>
```

### 16. FileTree (`@aui/file-tree`)
Collapsible directory and file hierarchy tree.
- Endpoint: `https://ui.arpitbhayani.me/r/file-tree.json`
- Props:
  - `data: FileTreeNode[]`
  - `onSelect?: (node: FileTreeNode) => void`
```tsx
<FileTree
  data={[
    {
      name: "src",
      type: "folder",
      defaultOpen: true,
      children: [
        { name: "index.ts", type: "file", badge: "TS" },
        { name: "Button.tsx", type: "file", badge: "React" },
      ],
    },
    { name: "package.json", type: "file", badge: "0.1.3" },
  ]}
/>
```

### 17. PackageManager (`@aui/package-manager`)
Multi-manager install command switcher with instant click-to-copy.
- Endpoint: `https://ui.arpitbhayani.me/r/package-manager.json`
- Props:
  - `pkg: string`
  - `defaultManager?: "pnpm" | "npm" | "bun" | "yarn"`
```tsx
<PackageManager pkg="array-ui" defaultManager="pnpm" />
```

---

## 5. Editorial & Content Primitives

### 18. Maxim (`@aui/maxim`)
Amber quotation callout box for engineering principles.
- Endpoint: `https://ui.arpitbhayani.me/r/maxim.json`
- Props:
  - `author?: string`
  - `source?: string`
  - `sourceUrl?: string`
  - `children: ReactNode`
```tsx
<Maxim author="Arpit Bhayani" source="Asli Engineering" sourceUrl="https://arpitbhayani.me">
  Simplicity is a prerequisite for reliability. Complex systems always fail in complex ways.
</Maxim>
```

### 19. TakeawaysBox (`@aui/takeaways-box`)
Crimson bulleted key takeaways callout.
- Endpoint: `https://ui.arpitbhayani.me/r/takeaways-box.json`
- Props:
  - `title?: string` (default: "Key Takeaways")
  - `items: string[]`
```tsx
<TakeawaysBox
  title="Key Takeaways"
  items={[
    "A write-ahead log ensures crash recovery is sequential and deterministic.",
    "Storage engines trade write amplification for read latency.",
  ]}
/>
```

### 20. Hero (`@aui/hero`)
Signature editorial portrait hero with bio and social pills.
- Endpoint: `https://ui.arpitbhayani.me/r/hero.json`
- Props:
  - `title: string`
  - `subtitle?: string`
  - `avatarUrl?: string`
  - `avatarAlt?: string`
  - `children?: ReactNode`
```tsx
<Hero
  title="Hey, I am Arpit"
  subtitle="engineering, databases, and systems."
  avatarUrl="https://edge.arpitbhayani.me/img/arpit-6.jpg"
  avatarAlt="Arpit Bhayani"
>
  <p>Principal engineer writing about the internals of systems that scale.</p>
</Hero>
```

### 21. SocialPill (`@aui/social-pill`)
Interactive platform pills for YouTube, X/Twitter, GitHub, LinkedIn.
- Endpoint: `https://ui.arpitbhayani.me/r/social-pill.json`
- Props:
  - `platform: "youtube" | "twitter" | "x" | "github" | "linkedin" | "substack" | "rss"`
  - `href: string`
  - `count?: string | number`
  - `label?: string`
```tsx
<SocialPill platform="github" href="https://github.com/arpitbbhayani" count="7k" />
<SocialPill platform="youtube" href="https://youtube.com/c/ArpitBhayani" count="210k" />
```

### 22. CourseCard (`@aui/course-card`)
Card for cohorts, courses, and open source projects.
- Endpoint: `https://ui.arpitbhayani.me/r/course-card.json`
- Props:
  - `title: string`
  - `description: string`
  - `href: string`
  - `badge?: string`
  - `tags?: string[]`
  - `ctaText?: string`
```tsx
<CourseCard
  title="System Design Masterclass"
  description="Consensus, storage engines, sharding, and real-world architectures."
  href="https://arpitbhayani.me/courses"
  badge="Live Cohort"
  tags={["Distributed", "Architecture"]}
  ctaText="Explore →"
/>
```

### 23. StatCard (`@aui/stat-card`)
Metric display card for dashboards and telemetry.
- Endpoint: `https://ui.arpitbhayani.me/r/stat-card.json`
- Props:
  - `value: string | number`
  - `label: string`
  - `description?: string`
  - `trend?: ReactNode`
```tsx
<StatCard value="99.98%" label="Uptime" description="rolling 30 days" />
```

### 24. EmptyState (`@aui/empty-state`)
Minimalist dashed container for empty states and zero-data screens.
- Endpoint: `https://ui.arpitbhayani.me/r/empty-state.json`
- Props:
  - `title: string`
  - `description?: string`
  - `children?: ReactNode`
```tsx
<EmptyState title="No clusters deployed" description="Create a cluster to begin telemetry.">
  <Button variant="primary" size="sm">New Cluster</Button>
</EmptyState>
```

### 25. Footer (`@aui/footer`)
Editorial 4-column directory footer with category hints, highlights, disclaimer, and social pills.
- Endpoint: `https://ui.arpitbhayani.me/r/footer.json`
- Props:
  - `copyright?: string`
  - `disclaimer?: string`
  - `socialPills?: ReactNode`
  - `columns?: FooterColumn[]`
```tsx
<Footer
  copyright={`© ${new Date().getFullYear()} Array UI. Built for systems engineers and autonomous coding agents. MIT Licensed.`}
  disclaimer="Array UI is an editorial design system for personal sites, developer SaaS, and technical documentation. Built with zero custom CSS, machined telemetry, and an agent-first component architecture."
  socialPills={
    <div style={{ display: "flex", gap: "0.5rem" }}>
      <SocialPill platform="github" href="https://github.com/arpitbbhayani/aui" label="GitHub" />
    </div>
  }
/>
```

### 26. Modal (`@aui/modal`)
Accessible dialog modal with backdrop blur, focus trapping, and escape-key dismissal.
- Endpoint: `https://ui.arpitbhayani.me/r/modal.json`
- Props:
  - `isOpen: boolean`
  - `onClose: () => void`
  - `title?: string`
  - `description?: string`
  - `children: ReactNode`
  - `footer?: ReactNode`
  - `size?: "sm" | "md" | "lg" | "xl"`
```tsx
<Modal isOpen={open} onClose={() => setOpen(false)} title="Confirmation" footer={<Button size="sm">Confirm</Button>}>
  <p>Modal body content</p>
</Modal>
```

### 27. VideoEmbed (`@aui/video-embed`)
Responsive 16:9 media player container with hairline border and fallback loading slot.
- Endpoint: `https://ui.arpitbhayani.me/r/video-embed.json`
- Props:
  - `src: string`
  - `title?: string`
  - `aspectRatio?: string` (default: "16 / 9")
```tsx
<VideoEmbed
  src="https://www.youtube-nocookie.com/embed/dQw4w9WgXcQ"
  title="System Architecture Walkthrough"
  aspectRatio="16 / 9"
/>
```

---

## 6. Technical Documentation Primitives

### 28. Canvas (`@aui/canvas`)
Engineering diagram frame with dotted coordinate grid and hairline border.
- Endpoint: `https://ui.arpitbhayani.me/r/canvas.json`
- Props:
  - `variant?: "plain" | "grid" | "ruled"` (default: "grid")
  - `frame?: boolean` (default: true)
  - `title?: string`
  - `badge?: ReactNode`
  - `footer?: ReactNode`
```tsx
<Canvas title="Storage Engine Architecture" variant="grid">
  <p>Diagram content here...</p>
</Canvas>
```

### 29. ApiEndpoint (`@aui/api-endpoint`)
Machined HTTP/gRPC API specification block with method pill, copyable paths, parameters, and response tabs.
- Endpoint: `https://ui.arpitbhayani.me/r/api-endpoint.json`
- Props:
  - `method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | string`
  - `path: string`
  - `description?: string`
  - `badge?: ReactNode`
  - `curl?: string`
  - `params?: ApiParam[]`
  - `responses?: ApiResponseTab[]`
```tsx
<ApiEndpoint
  method="POST"
  path="/v1/clusters/{cluster_id}/replicate"
  description="Triggers immediate Raft log replication across active quorum peers."
  params={[
    { name: "cluster_id", type: "string", required: true, description: "Unique cluster identifier" },
    { name: "sync", type: "boolean", required: false, description: "Wait for write-ahead log fsync" },
  ]}
  responses={[
    { status: 200, label: "OK", body: '{\n  "replicated_index": 45091,\n  "peers_acknowledged": 3\n}' },
    { status: 409, label: "Conflict", body: '{\n  "error": "LEADER_DEPOSED",\n  "term": 4\n}' },
  ]}
/>
```

### 30. DocStepper (`@aui/doc-stepper`)
Connected numbered step walkthrough for tutorials, runbooks, and installation guides.
- Endpoint: `https://ui.arpitbhayani.me/r/doc-stepper.json`
- Props:
  - `steps: DocStepItem[]`
  - `activeStep?: number`
```tsx
<DocStepper
  steps={[
    { title: "Initialize Ledger", description: "Bootstrap root node on port 8080." },
    { title: "Join Quorum Peers", description: "Attach secondary voter replicas." },
    { title: "Verify Health", description: "Poll heartbeat ping status." },
  ]}
  activeStep={1}
/>
```

### 31. ParamTable (`@aui/param-table`)
Dense configuration options and parameter reference table with types, required badges, and defaults.
- Endpoint: `https://ui.arpitbhayani.me/r/param-table.json`
- Props:
  - `items: ParamItem[]`
```tsx
<ParamTable
  items={[
    { name: "--wal-dir", type: "string", required: true, description: "Directory path for write-ahead logs" },
    { name: "--sync-interval", type: "Duration", required: false, default: "100ms", description: "Disk sync frequency" },
  ]}
/>
```

### 32. FeatureMatrix (`@aui/feature-matrix`)
Dense matrix comparison table comparing engines, editions, or versions with status indicators.
- Endpoint: `https://ui.arpitbhayani.me/r/feature-matrix.json`
- Props:
  - `columns: FeatureMatrixColumn[]`
  - `rows: FeatureMatrixRow[]`
```tsx
<FeatureMatrix
  columns={[
    { key: "lsm", label: "LSM-Tree" },
    { key: "btree", label: "B+ Tree" },
  ]}
  rows={[
    { category: "Storage Performance" },
    { name: "Write Amplification", values: { lsm: "Low (Sequential)", btree: "High (Random I/O)" } },
    { name: "Point Lookups", values: { lsm: "partial", btree: true } },
  ]}
/>
```

### 33. VersionSelector (`@aui/version-selector`)
Compact documentation version switcher and runtime environment selector.
- Endpoint: `https://ui.arpitbhayani.me/r/version-selector.json`
- Props:
  - `label?: string`
  - `versions: VersionOption[]`
  - `defaultValue?: string`
  - `onChange?: (val: string) => void`
```tsx
<VersionSelector
  label="API Version:"
  versions={[
    { label: "v2.4", value: "v2.4", badge: "Latest" },
    { label: "v2.3", value: "v2.3" },
    { label: "v1.9", value: "v1.9", badge: "LTS" },
  ]}
/>
```

---

## 7. Interactive Explorables & Systems Visualizers

### 34. MemoryLayout (`@aui/memory-layout`)
Contiguous byte/memory layout visualizer with offsets, binary structs, and interactive field inspector.
- Endpoint: `https://ui.arpitbhayani.me/r/memory-layout.json`
- Props:
  - `title?: string`
  - `totalBytes?: number | string`
  - `segments: MemorySegment[]`
```tsx
<MemoryLayout
  title="TCP Header Segment (20 Bytes)"
  segments={[
    { name: "Source Port", bytes: 2, offset: "0x00 - 0x01", type: "uint16", color: "crimson" },
    { name: "Destination Port", bytes: 2, offset: "0x02 - 0x03", type: "uint16", color: "emerald" },
    { name: "Sequence Number", bytes: 4, offset: "0x04 - 0x07", type: "uint32", color: "blue" },
    { name: "Acknowledgment", bytes: 4, offset: "0x08 - 0x0B", type: "uint32", color: "amber" },
  ]}
/>
```

### 35. PipelineFlow (`@aui/pipeline-flow`)
Multi-stage data pipeline flow visualizer with throughput metrics and animated pulse lines.
- Endpoint: `https://ui.arpitbhayani.me/r/pipeline-flow.json`
- Props:
  - `stages: PipelineStageItem[]`
  - `animated?: boolean`
```tsx
<PipelineFlow
  stages={[
    { title: "Ingress", badge: "HTTP", metric: "62k req/s" },
    { title: "WAL Log", badge: "Disk", metric: "fsync 0.4ms", active: true },
    { title: "MemTable", badge: "RAM", metric: "SkipList" },
    { title: "SSTable", badge: "Storage", metric: "Level-0" },
  ]}
/>
```

### 36. BenchmarkDelta (`@aui/benchmark-delta`)
Comparative system performance delta block showing baseline vs candidate metrics.
- Endpoint: `https://ui.arpitbhayani.me/r/benchmark-delta.json`
- Props:
  - `benchmarks: BenchmarkItem[]`
```tsx
<BenchmarkDelta
  benchmarks={[
    {
      name: "Throughput (ops/sec)",
      baselineValue: 42000,
      baselineDisplay: "42,000 ops/s",
      candidateValue: 98000,
      candidateDisplay: "98,000 ops/s",
      delta: "+133%",
      better: "higher",
    },
    {
      name: "Heap Allocations",
      baselineValue: 120,
      baselineDisplay: "120 MB",
      candidateValue: 34,
      candidateDisplay: "34 MB",
      delta: "-71%",
      better: "lower",
    },
  ]}
/>
```

### 37. LatencyDistribution (`@aui/latency-distribution`)
Percentile latency distribution bar (p50, p75, p90, p99, p99.9) with color thresholds and SLA lines.
- Endpoint: `https://ui.arpitbhayani.me/r/latency-distribution.json`
- Props:
  - `title?: string`
  - `sla?: string`
  - `percentiles: LatencyBracket[]`
```tsx
<LatencyDistribution
  title="Gateway Latency"
  sla="Target: p99 < 50ms"
  percentiles={[
    { label: "p50", value: 1.2, display: "1.2ms", color: "emerald" },
    { label: "p90", value: 4.8, display: "4.8ms", color: "blue" },
    { label: "p99", value: 18.5, display: "18.5ms", color: "amber" },
    { label: "p99.9", value: 84.1, display: "84.1ms", color: "rose" },
  ]}
/>
```



### 39. ClusterState (`@aui/cluster-state`)
Distributed consensus cluster topology visualizer (Leader, Followers, Candidates, Quorum status).
- Endpoint: `https://ui.arpitbhayani.me/r/cluster-state.json`
- Props:
  - `title?: string`
  - `nodes: ClusterNodeItem[]`
  - `requiredQuorum?: number`
```tsx
<ClusterState
  title="Raft Consensus Cluster"
  nodes={[
    { id: "node-01", role: "leader", term: 4, latency: "0.2ms" },
    { id: "node-02", role: "follower", term: 4, latency: "1.4ms" },
    { id: "node-03", role: "follower", term: 4, latency: "1.1ms" },
    { id: "node-04", role: "follower", term: 4, latency: "2.3ms" },
    { id: "node-05", role: "offline", term: 3 },
  ]}
/>
```

### 40. ParamSandbox (`@aui/param-sandbox`)
Interactive slider sandbox for mathematical formulas and live reactive system calculations.
- Endpoint: `https://ui.arpitbhayani.me/r/param-sandbox.json`
- Props:
  - `formula: string`
  - `inputs: SandboxInput[]`
  - `outputs: SandboxOutput[]`
```tsx
<ParamSandbox
  formula="Quorum Q = floor(N / 2) + 1, Max Tolerable Failures F = floor((N - 1) / 2)"
  inputs={[
    { id: "nodes", label: "Cluster Nodes (N)", min: 3, max: 11, step: 2, defaultValue: 5 },
  ]}
  outputs={[
    { label: "Required Quorum (Q)", compute: (v) => Math.floor(v.nodes / 2) + 1 },
    { label: "Tolerable Failures (F)", compute: (v) => Math.floor((v.nodes - 1) / 2) },
  ]}
/>
```

---

## 7b. Architecture Views from a Repository (ArchitectureCanvas)
Install: `npx shadcn@latest add @aui/architecture-canvas -y`. To turn a codebase into an interactive diagram:
1. List components (services, packages, datastores, queues, external systems): one node per meaningful unit, 8 to 30 nodes.
2. Give each node a stable `id`, short `label`, `badge` (language or kind), and one-line `description`.
3. Set `group` to the owning package or service and declare it in `groups` (`kind`: service, layer, package, external). Groups collapse into one node.
4. Add one connection per dependency (caller to callee) with a short `label`; use `variant: "dashed"` for async edges.
5. Do NOT set `x`/`y`: the canvas auto-layouts (`direction="LR"` or `"TB"`). Explicit `x`/`y` still pins a node. Auto-layout targets about 40 nodes or fewer and does not nest groups.
```tsx
<ArchitectureCanvas
  title="Checkout Service"
  groups={[{ id: "core", label: "Core", kind: "service" }]}
  nodes={[
    { id: "web", label: "Web App" },
    { id: "api", label: "API Gateway", group: "core" },
    { id: "orders", label: "Orders", group: "core" },
  ]}
  connections={[
    { from: "web", to: "api", label: "HTTPS" },
    { from: "api", to: "orders", label: "gRPC" },
  ]}
/>
```

---

## 8. Layout & Utility Classes

- `.aui-container`: Max-width 1280px standard container with responsive padding.
- `.aui-container-md`: Intermediate max-width 900px container for reading and forms.
- `.aui-theatre-grid`: Responsive 2-column player layout (`minmax(0, 1fr) 340px`).
- `.aui-prose-app` / `.aui-prose-compact`: Dense 15px prose typography for UI tab panels and cards.
- `.aui-input-row`: Flex row for inline inputs with adjacent action buttons.
- `.aui-form-hint`: Subtle helper text beneath inputs.