react-dashstream 0.3.1 → 0.3.3

package/skills/dashstream-component-dialogs/SKILL.md

@@ -0,0 +1,287 @@
+---
+name: dashstream-component-dialogs
+description: Configure drill-down dialogs with custom metrics, internals, sparklines, and alerts
+license: MIT
+compatibility: opencode
+metadata:
+  audience: developers
+  workflow: react
+---
+
+## What I do
+
+- Document the ComponentDialog system (gauges, drill-down internals, sparkline graphs)
+- Explain `dialogMetrics`, `subComponents`, and `graphSeries` props
+- Cover automatic threshold-based alerts and custom alert positioning
+- Show how to wire live data into dialog metrics via service props
+
+## When to use me
+
+Use this when customizing what appears in the drill-down panel when a user clicks a node — custom gauges, internal 3D sub-components, sparkline charts, or alert callouts.
+
+---
+
+## Component dialog — default gauges
+
+The **ComponentDialog** appears when clicking a node. Default gauges are derived from node type:
+
+- **Server**: CPU (from `cpuLoad`), Memory (from `memLoad`), Storage
+- **Database**: Capacity (from `capacity`), Memory, Storage
+- **Dispatcher**: Traffic (from `traffic`), Memory, Storage
+- **Message Server**: Queue (from `queueDepth`), Memory, Storage
+
+Default thresholds: warn at 70, critical at 85.
+
+---
+
+## Custom dialogMetrics
+
+Override default gauges with `dialogMetrics` on any compound node:
+
+```tsx
+<ServerNode
+    name="SRV-01"
+    status="online"
+    cpuLoad={67}
+    memLoad={72}
+    ex={200} ey={380}
+    compactOffset={{ x: -30, y: -20 }}
+    zIndex={8}
+    dialogMetrics={[
+        { id: "cpu", label: "CPU", sublabel: "PROCESSOR", value: 67, unit: "%" },
+        { id: "mem", label: "MEMORY", sublabel: "HEAP USAGE", value: 72, unit: "%" },
+        { id: "iops", label: "IOPS", sublabel: "DISK OPS", value: 45, unit: "k/s", icon: "disk" },
+        {
+            id: "threads",
+            label: "THREADS",
+            sublabel: "ACTIVE",
+            value: 82,
+            unit: "%",
+            warnAt: 60,
+            critAt: 80,
+            icon: "cpu",
+        },
+    ]}
+/>
+```
+
+```ts
+interface ComponentDialogMetric {
+    id: string;        // Unique key
+    label: string;     // Upper label
+    sublabel: string;  // Lower label
+    value: number;     // 0–100
+    unit?: string;     // Default "%"
+    icon?: "cpu" | "mem" | "disk";  // Default "cpu"
+    warnAt?: number;   // Default 70
+    critAt?: number;   // Default 85
+    color?: string;    // Override bar color (bypasses threshold coloring)
+}
+```
+
+All compound nodes accept `dialogMetrics`: `ServerNode`, `DatabaseNode`, `WebDispatcherNode`, `MessageServerNode`.
+
+**When provided, all default gauges are removed** — you must define every metric you want shown.
+
+---
+
+## Drill-down internals — custom subComponents
+
+When clicking a node, the drill-down shows internal 3D sub-components. Default sub-components are auto-generated per type. Override with `subComponents`:
+
+```tsx
+import { CPU3D, Memory3D, DriveBay3D, ThreadPool3D, NetworkBlock3D, Platter3D, Port3D } from "react-dashstream";
+import type { SubComponentConfig } from "react-dashstream";
+
+const internals: SubComponentConfig[] = [
+    { id: "cpu-0", label: "CPU-0", status: "online",
+      element: <CPU3D label="CPU-0" load={67} color="#00e5ff" /> },
+    { id: "heap", label: "HEAP", status: "warning",
+      element: <Memory3D label="HEAP" usedPercent={92} color="#8855ee" status="warning" /> },
+    { id: "drive", label: "DRIVE-0", status: "online",
+      element: <DriveBay3D label="DRIVE-0" color="#00e5ff" activity={true} /> },
+    { id: "threads", label: "THREADS", status: "online",
+      element: <ThreadPool3D label="THREADS" color="#00e5ff" /> },
+    { id: "net", label: "NET", status: "online",
+      element: <NetworkBlock3D label="NET" color="#00e5ff" /> },
+];
+
+<ServerNode subComponents={internals} ... />
+```
+
+```ts
+interface SubComponentConfig {
+    id: string;           // Unique key
+    label: string;        // Display name
+    status: ComponentStatus;  // LED color
+    detail?: string;      // Fault description
+    element: ReactNode;   // 3D element to render
+}
+```
+
+All compound nodes accept `subComponents`. **When provided, all auto-generated sub-components are removed.**
+
+---
+
+## Graph series — custom sparklines
+
+The drill-down's historical panel shows sparkline charts. Default graphs are auto-generated. Override with `graphSeries`:
+
+```tsx
+import type { GraphSeries } from "react-dashstream";
+
+const graphs: GraphSeries[] = [
+    { id: "cpu",  label: "CPU-0",  unit: "%",   color: "#00e5ff", data: [45, 52, 67, 71, 68, 55] },
+    { id: "mem",  label: "HEAP",   unit: "%",   color: "#8855ee", data: [60, 65, 72, 78, 82, 75] },
+    { id: "iops", label: "DISK",   unit: "k/s", color: "#ff8c00", data: [12, 15, 22, 18, 25, 20] },
+];
+
+<ServerNode graphSeries={graphs} ... />
+```
+
+```ts
+interface GraphSeries {
+    id: string;       // Unique key
+    label: string;    // Label above sparkline
+    unit: string;     // Suffix
+    color: string;    // Line color
+    data: number[];   // Points (most recent last)
+}
+```
+
+All compound nodes accept `graphSeries`. **When provided, all auto-generated sparklines are removed.**
+
+---
+
+## Alerts — automatic threshold detection
+
+Nodes auto-render `NodeCallout` alerts when metrics breach thresholds:
+
+- **Warning** at 70% → orange callout
+- **Critical** at 85% → red callout
+
+Sources (checked in priority order):
+
+1. `dialogMetrics` values vs their `warnAt`/`critAt`
+2. Context values (`cpuLoad`, `memLoad`, `traffic`, `queueDepth`, `capacity`) vs default thresholds
+
+```tsx
+// Auto-alert from cpuLoad > 85
+<ServerNode cpuLoad={92} memLoad={64}
+    alert={{ offsetX: -160, offsetY: -60, align: "left" }}
+    ... />
+
+// Custom message
+<ServerNode cpuLoad={92}
+    alert={{ msg: "CPU overload — scale out", offsetX: -160, offsetY: -60, align: "left" }}
+    ... />
+
+// Custom thresholds via dialogMetrics
+<ServerNode
+    dialogMetrics={[
+        { id: "cpu", label: "CPU", sublabel: "PROCESSOR", value: 67,
+          warnAt: 50, critAt: 75 },
+    ]}
+    alert={{ offsetX: -160, offsetY: -60, align: "left" }}
+    ... />
+```
+
+### Alert prop shape
+
+```ts
+alert?: {
+    msg?: string;         // Custom message (auto-generated if omitted)
+    offsetX?: number;     // X offset from node (default 110)
+    offsetY?: number;     // Y offset from node (default -30)
+    align?: "left" | "right" | "top" | "bottom";  // Default "right"
+    internalRef?: string; // Sub-component ID
+}
+```
+
+Alert `align` options: `"left"`, `"right"`, `"top"`, `"bottom"`.
+
+---
+
+## ServiceDialog — static and live metrics
+
+The **ServiceDialog** panel shows KPIs when a service is expanded.
+
+### Static metrics via ServiceMeta
+
+```tsx
+const services: ServiceMeta[] = [
+    {
+        name: "My Service",
+        status: "online",
+        metrics: [
+            { label: "Uptime", value: "99.99%", color: "#00ff88" },
+            { label: "Avg Latency", value: "8ms", color: "#00e5ff" },
+        ],
+        alerts: [
+            { level: "info", message: "All Systems Nominal" },
+            { level: "warning", message: "High CPU on SRV-01" },
+            { level: "critical", message: "DB connection pool exhausted" },
+        ],
+    },
+];
+```
+
+### Live metrics via serviceDataBindings
+
+See **dashstream-live-data** for `serviceDataBindings` configuration.
+
+---
+
+## Full example — service with all dialog features
+
+```tsx
+import { CPU3D, Memory3D } from "react-dashstream";
+
+function MyService({ name, status, cpuLoad, memLoad, dbCapacity, dbStatus }: any) {
+    return (
+        <Service
+            name={name}
+            status={status ?? "online"}
+            connections={[
+                { from: [330, 200], to: [200, 380], visibleAtPhase: 3 },
+                { from: [330, 200], to: [460, 380], visibleAtPhase: 3 },
+            ]}
+        >
+            <ServerNode
+                ex={200} ey={380}
+                compactOffset={{ x: -30, y: -20 }}
+                zIndex={8}
+                name="SRV-01"
+                subLabel="APP SERVER"
+                status={status ?? "online"}
+                cpuLoad={cpuLoad ?? 42}
+                memLoad={memLoad ?? 60}
+                alert={{ offsetX: -160, offsetY: -60, align: "left" }}
+                dialogMetrics={[
+                    { id: "cpu", label: "CPU", sublabel: "PROCESSOR", value: cpuLoad ?? 42 },
+                    { id: "mem", label: "MEMORY", sublabel: "HEAP", value: memLoad ?? 60 },
+                ]}
+                subComponents={[
+                    { id: "cpu", label: "CPU-0", status: "online",
+                      element: <CPU3D label="CPU-0" load={cpuLoad ?? 42} /> },
+                    { id: "mem", label: "HEAP", status: "online",
+                      element: <Memory3D label="HEAP" usedPercent={memLoad ?? 60} /> },
+                ]}
+                graphSeries={[
+                    { id: "cpu", label: "CPU", unit: "%", color: "#00e5ff", data: [45, 52, 67, 71, 68] },
+                ]}
+            />
+            <DatabaseNode
+                ex={460} ey={380}
+                compactOffset={{ x: 30, y: -20 }}
+                zIndex={7}
+                name="DB-01"
+                subLabel="PRIMARY"
+                status={dbStatus ?? "online"}
+                capacity={dbCapacity ?? 55}
+                alert={{ offsetX: 160, offsetY: -60, align: "right" }}
+            />
+        </Service>
+    );
+}
+```

package/skills/dashstream-core/SKILL.md

@@ -0,0 +1,330 @@
+---
+name: dashstream-core
+description: React DashStream package overview, installation, theming, architecture, exports, and types
+license: MIT
+compatibility: opencode
+metadata:
+  audience: developers
+  workflow: react
+---
+
+## What I do
+
+- Explain the `react-dashstream` package structure, exports, and type system
+- Guide correct installation and CSS import
+- Document light/dark theming and `ThemeProvider` usage
+- Provide the full architecture tree and source layout
+- List all public exports and common pitfalls
+
+## When to use me
+
+Use this when starting a new project with `react-dashstream`, need the import list, want to understand the component hierarchy, or are troubleshooting theme / CSS issues.
+
+For specific features, see sibling skills:
+
+- **dashstream-3d-dashboard** — `AIOPsDashboard`, services, nodes, positioning
+- **dashstream-live-data** — `DataProvider`, data bindings, hooks, endpoint contract
+- **dashstream-component-dialogs** — drill-down metrics, internals, graph series, alerts
+- **dashstream-event-view** — `EventView`, event API, field mapping
+- **dashstream-datacenter-view** — `DatacenterView`, topology map, geography, buildings
+
+---
+
+## Package basics
+
+> **Package**: `react-dashstream` (npm)
+> **Version**: 0.2.0
+> **Peer deps**: `react` ^18 || ^19, `react-dom` ^18 || ^19
+> **License**: MIT
+
+React DashStream renders a rotating 3D carousel of infrastructure services using CSS 3D transforms (no WebGL, no canvas). Each service expands into a multi-tiered topology with servers, databases, dispatchers, message servers, and user nodes connected by animated SVG lines. Components can be drilled into to reveal internal sub-components with sparkline graphs and gauges.
+
+Two modes:
+
+1. **Static mode** — pass props directly for demo or snapshot views.
+2. **Live data mode** — poll an HTTP endpoint with PromQL queries and auto-inject resolved values as component props.
+
+---
+
+## Installation and CSS
+
+```bash
+npm install react-dashstream
+```
+
+```tsx
+import "react-dashstream/dist/index.css";
+import { AIOPsDashboard, Service, ServerNode, DatabaseNode } from "react-dashstream";
+```
+
+**Always import the CSS file** — without it, no styles render.
+
+---
+
+## Light / dark theme
+
+The dashboard supports **`"light"`** and **`"dark"`** modes.
+
+- **`AIOPsDashboard`** defaults to **light** and exposes a header toggle. Use **`backgroundImage`** (dark) and **`lightBackgroundImage`** (light when set).
+- **Controlled mode:** pass **`theme`** and **`onThemeChange`** (`DashboardTheme`) so parent state owns the mode (e.g. sync app chrome + `EventView`).
+- **`ThemeProvider`** (export) + **`useTheme()`** — wrap subtrees so **`EventView`**, **`CredentialsModal`**, **`ServiceDialog`**, and **`ComponentDialog`** match the dashboard. Without a provider, `useTheme()` defaults to **`"dark"`**; prefer wrapping when using `EventView` or the lock screen next to a light dashboard.
+- **`EventView`** accepts optional **`theme`** to override context.
+
+When generating multi-view apps (3D + Event Console + credentials), wrap the root in **`ThemeProvider`** with the same value passed to **`AIOPsDashboard`**'s controlled props.
+
+---
+
+## Architecture
+
+```
+AIOPsDashboard              ← Shell: header, state, optional DataProvider
+  └─ Carousel               ← 3D orbit, rotation, hosts dialogs
+       └─ Service            ← Per-service container, connections, holo base
+            ├─ ServerNode         ← Compound: ServiceNode + Server3D
+            ├─ DatabaseNode       ← Compound: ServiceNode + Database3D
+            ├─ WebDispatcherNode  ← Compound: ServiceNode + WebDispatcher3D
+            ├─ MessageServerNode  ← Compound: ServiceNode + MessageServer3D
+            ├─ HumanNode          ← Compound: ServiceNode + Human3D (SVG)
+            ├─ SvgConnection      ← Animated dashed topology line
+            ├─ SyncBridge         ← DB replication indicator
+            ├─ NodeCallout        ← Alert callout (auto from thresholds)
+            └─ HoloBase           ← Neon platform (auto-rendered)
+
+ServiceDialog               ← Service-level KPI panel (auto on expand)
+ComponentDialog              ← Drill-down with internals + graphs
+  ├─ HistoricalGraphPanel    ← Sparkline charts
+  └─ CPU3D / Memory3D / DriveBay3D / NetworkBlock3D / ThreadPool3D / Platter3D / Port3D
+
+DataProvider                 ← Polling engine + credentials modal
+
+EventView                    ← Standalone event console (table view)
+
+DatacenterView               ← SVG topology / optional geography map + drill-down dashboard
+```
+
+### Source layout
+
+```
+src/
+├── index.ts                 # Public API barrel
+├── AIOPsDashboard.tsx       # Dashboard shell + live-data wiring
+├── types.ts                 # Shared topology/drill-down types
+├── theme.ts                 # Status tokens, holo palette, 3D face helpers
+├── ThemeContext.ts           # DashboardTheme, ThemeProvider, useTheme
+├── styles.css / index.css   # Library + dashboard styles
+├── data/
+│   ├── DataProvider.tsx      # Polling engine, context, hooks
+│   ├── CredentialsModal.tsx  # Auth prompt UI
+│   └── index.ts
+├── components/              # ~30 UI components
+│   ├── Carousel.tsx, Service.tsx, ServiceNode.tsx
+│   ├── ServerNode.tsx, DatabaseNode.tsx, WebDispatcherNode.tsx, etc.
+│   ├── Server3D.tsx, Database3D.tsx, etc.
+│   ├── ServiceDialog.tsx, ComponentDialog.tsx
+│   ├── Internal3DComponents.tsx, HistoricalGraphPanel.tsx
+│   ├── ComponentDrillView.tsx, SvgConnection.tsx, SyncBridge.tsx
+│   ├── NodeCallout.tsx, HoloBase.tsx, CarouselContext.ts
+│   ├── EventView/                  # Operations event console
+│   │   ├── EventView.tsx           # Table component
+│   │   ├── EventView.css
+│   │   ├── EventAlertsContext.tsx   # EventAlertsProvider + per-host alert map
+│   │   ├── fetchEvents.ts          # Shared fetch/mapping logic
+│   │   ├── types.ts
+│   │   ├── mockData.ts             # 28 realistic mock events
+│   │   └── index.ts
+│   ├── DatacenterView/             # Topology map + CSS 3D building markers
+│   │   ├── DatacenterView.tsx
+│   │   ├── DatacenterView.css
+│   │   ├── buildings.tsx           # DatacenterSite, TowerDC, FlatDC, …
+│   │   ├── collectDatacenterTree.ts
+│   │   ├── types.ts
+│   │   └── index.ts
+│   └── index.ts
+├── services/
+│   ├── SAPService.tsx, ExchangeService.tsx
+│   ├── sapSubComponents.tsx
+│   └── index.ts
+example/
+├── Dashboard.tsx
+└── services/
+```
+
+---
+
+## Exports
+
+Everything below is exported from `react-dashstream`.
+
+### Default export
+
+`AIOPsDashboard` — main dashboard shell component.
+
+### Compound nodes
+
+`ServerNode`, `DatabaseNode`, `WebDispatcherNode`, `MessageServerNode`, `HumanNode`
+
+### Layout
+
+`Carousel`, `Service`, `ServiceNode`
+
+### 3D models
+
+`Server3D`, `Database3D`, `WebDispatcher3D`, `MessageServer3D`, `Human3D`
+
+### Internal 3D components (for drill-down)
+
+`CPU3D`, `Memory3D`, `DriveBay3D`, `NetworkBlock3D`, `ThreadPool3D`, `Platter3D`, `Port3D`
+
+### Indicators and connections
+
+`SvgConnection`, `SyncBridge`, `NodeCallout`, `HoloBase`
+
+### Dialogs
+
+`ServiceDialog`, `ComponentDialog`, `HistoricalGraphPanel`, `ComponentDrillView`
+
+### Pre-built services
+
+`SAPService`, `ExchangeService`
+
+SAP helpers: `computeSAPServiceStatus`, `computeSAPDialogMetrics`, `computeSAPDialogAlerts`, `SAP_CONNECTIONS`
+
+Exchange helpers: `computeExchangeServiceStatus`, `computeExchangeDialogMetrics`, `computeExchangeDialogAlerts`, `EXCHANGE_CONNECTIONS`
+
+SAP sub-component helpers: `getServerSubComponents`, `getServerGraphSeries`, `getDispatcherSubComponents`, `getDispatcherGraphSeries`, `getMessageServerSubComponents`, `getMessageServerGraphSeries`, `getDatabaseSubComponents`, `getDatabaseGraphSeries`
+
+### Data layer
+
+`DataProvider`, `useAIOpsData`, `useAIOpsDataOptional`, `useQueryResult`, `extractUniqueQueries`, `extractDatacenterMetricQueries`, `defaultDataTransform`
+
+### Datacenter topology map
+
+`DatacenterView`, `DatacenterSite`, shape components (`StandardDC`, `TowerDC`, `FlatDC`, `StorageDC`, `GoogleDC`, `MicroDC`, `OfficeDC`), generic `Datacenter`, `collectDatacenterTree`, `getBuildingVariant`, and types `DatacenterViewProps`, `DatacenterBuildingConfig`, `DatacenterBuildingNodeProps`, `DatacenterBuildingVariant`, `DatacenterConnection`, `DatacenterGeography`, `DatacenterMetrics`, `DatacenterProps`, `DatacenterSiteLabels`, `DatacenterSiteProps`, `DatacenterViewPhase`, `CollectedTopology`
+
+### Event alerts
+
+`EventAlertsProvider`, `useEventAlerts`, `useEventAlertsOptional`
+
+### Theme
+
+`STATUS_CFG`, `HOLO_CYAN` (`"#00e5ff"`), `HOLO_BLUE` (`"#0055cc"`), `HOLO_SURFACE`, `HOLO_GLASS`, `makeFaceStyles(W, H, D)`
+
+`ThemeProvider`, `useTheme`, type `DashboardTheme` (`"light" | "dark"`)
+
+### Context hooks
+
+`CarouselContext`, `CarouselItemContext`, `useCarouselContext`, `useCarouselItemContext`, `ServiceContext`
+
+### Type exports
+
+`AIOPsDashboardProps`, `ServiceMeta`, `ServiceMetricBinding`, `DashboardTheme`, `ComponentStatus`, `StatusCfg`, `FaceName`, `Base3DProps`, `ComponentType`, `ComponentContext`, `ComponentDialogMetric`, `SubComponentConfig`, `GraphSeries`, `SelectedComponent`, `ConnectionConfig`, `ViewState`, `DataBinding`, `DataBindings`, `DatacenterMetricBindings`, `DataProviderConfig`, `Credentials`, `DataContextValue`, `ServiceProps`, `ServiceContextValue`, `ServiceNodeProps`, `CarouselProps`, `ServerNodeProps`, `DatabaseNodeProps`, `HumanNodeProps`, `WebDispatcherNodeProps`, `MessageServerNodeProps`, `SvgConnectionProps`, `SyncBridgeProps`, `NodeCalloutProps`, `ServiceDialogProps`, `ServiceDialogMetric`, `ServiceDialogAlert`, `ComponentDialogProps`, `ComponentDrillViewProps`, `CarouselContextValue`, `CarouselItemContextValue`, `SAPServiceProps`, `SAPServiceOwnProps`, `SAPServiceConfig`, `ExchangeServiceProps`, `ExchangeServiceOwnProps`, `ExchangeServiceConfig`, `EventHostAlert`, `EventAlertsContextValue`, `EventAlertsProviderProps`, `DatacenterViewProps`, `DatacenterBuildingConfig`, `DatacenterBuildingNodeProps`, `DatacenterBuildingVariant`, `DatacenterConnection`, `DatacenterGeography`, `DatacenterMetrics`, `DatacenterProps`, `DatacenterSiteLabels`, `DatacenterSiteProps`, `DatacenterViewPhase`, `CollectedTopology`
+
+---
+
+## Key types quick reference
+
+### ComponentStatus
+
+```ts
+type ComponentStatus = "online" | "warning" | "critical" | "offline";
+```
+
+| Status     | Color     | Glow     |
+| ---------- | --------- | -------- |
+| `online`   | `#00e5ff` | cyan     |
+| `warning`  | `#ff8c00` | orange   |
+| `critical` | `#ff2255` | red      |
+| `offline`  | `#1e3a5a` | dim blue |
+
+### AIOPsDashboardProps
+
+`DashboardTheme` is `"light" | "dark"` (exported).
+
+```ts
+interface AIOPsDashboardProps {
+    title?: string;
+    brandName?: string;                // Default: "BUSAUD AIOps"
+    brandTag?: string;                 // Default: "3D MONITOR"
+    services?: ServiceMeta[];
+    backgroundImage?: string;
+    lightBackgroundImage?: string;     // Used in light mode when set
+    theme?: DashboardTheme;            // Controlled theme (pair with onThemeChange)
+    onThemeChange?: (theme: DashboardTheme) => void;
+    logoUrl?: string;
+    carouselSpeed?: number;            // Default: 0.006
+    fontFamily?: string;
+    liveData?: boolean;                // Default: false
+    dataEndpoint?: string;
+    dataBindings?: DataBindings;
+    dataTransform?: (raw: unknown) => unknown;
+    dataRefreshInterval?: number;      // Default: 60000
+    serviceDataBindings?: Record<string, ServiceMetricBinding[]>;
+    eventApiConfig?: EventApiConfig;   // Enable event-to-dashboard bridge
+    children: React.ReactNode;
+}
+```
+
+### ServiceMeta
+
+```ts
+interface ServiceMeta {
+    name: string;       // Must match child component name
+    status: ComponentStatus;
+    dbSync?: boolean;   // Default: true
+    metrics?: ServiceDialogMetric[];
+    alerts?: ServiceDialogAlert[];
+}
+
+interface ServiceDialogMetric {
+    label: string;
+    value: string;
+    color: string;
+}
+
+interface ServiceDialogAlert {
+    level: "info" | "warning" | "critical";
+    message: string;
+}
+```
+
+### ConnectionConfig
+
+```ts
+interface ConnectionConfig {
+    from: [number, number];
+    to: [number, number];
+    visibleAtPhase?: number;   // Default: 0
+    color?: string;            // Default: "#00e5ff"
+    duration?: string;         // Default: "1.2s"
+}
+```
+
+---
+
+## Build and development
+
+```bash
+npm run dev          # Vite dev server (loads example/Dashboard.tsx)
+npm run build        # TypeScript check + Vite library build
+npm run build:lib    # Vite library build only
+npm run preview      # Preview production build
+```
+
+Output: `dist/index.js` (ESM), `dist/index.d.ts`, `dist/index.css`.
+
+---
+
+## Common pitfalls
+
+1. **Missing CSS import** — Always import `react-dashstream/dist/index.css`.
+2. **Name mismatch** — `name` on child components must exactly match keys in `dataBindings`, `serviceDataBindings`, and `ServiceMeta.name`.
+3. **Credentials are in-memory only** — Page refresh requires re-entering credentials.
+4. **Default transform is plain-text** — For JSON endpoints, provide a custom `dataTransform`.
+5. **Polling only** — No WebSocket/SSE support; uses `setInterval`.
+6. **`visibleAtPhase` matters** — Nodes without proper values won't animate during expansion.
+7. **Connection coordinates** — `from`/`to` arrays use `[x, y]` matching `ex`/`ey` of connected nodes.
+8. **`dialogMetrics` replaces defaults** — When provided, all default gauges (CPU/Memory/Storage) are removed.
+9. **`subComponents` replaces defaults** — When provided, all auto-generated sub-components are removed.
+10. **`graphSeries` replaces defaults** — When provided, all auto-generated sparklines are removed.
+11. **Event bridge matching** — Node `name` must match event `host` (case-insensitive) for `eventApiConfig` to highlight nodes automatically.
+12. **Theme context** — `EventView` and `CredentialsModal` use `useTheme()`. Without `ThemeProvider`, context defaults to `"dark"`. Wrap the app (or use `EventView`'s `theme` prop) so light dashboards are not paired with a dark event console or lock screen.