react-dashstream 0.0.8 → 0.0.9

package/dashstream-skill.md

@@ -0,0 +1,842 @@
+# React DashStream — AI Coding Assistant Skill
+
+> **Package**: `react-dashstream` (npm)
+> **Version**: 0.0.4
+> **Peer deps**: `react` ^18 || ^19, `react-dom` ^18 || ^19
+> **License**: MIT
+
+Use this skill when the user is working with the `react-dashstream` package — a holographic 3D infrastructure monitoring dashboard built entirely with CSS 3D transforms (no WebGL, no canvas).
+
+---
+
+## What this package does
+
+React DashStream renders a rotating 3D carousel of infrastructure services. Each service can be clicked to expand into a multi-tiered topology showing 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.
+
+---
+
+## 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
+```
+
+### 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
+├── 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
+│   └── index.ts
+├── services/
+│   ├── SAPService.tsx, ExchangeService.tsx
+│   ├── sapSubComponents.tsx
+│   └── index.ts
+example/
+├── Dashboard.tsx
+└── services/
+```
+
+---
+
+## Complete data flow reference
+
+There are **9 distinct data paths** in this package. Understanding them is critical for building live dashboards.
+
+### 1. Data bindings — live props injected into service components
+
+`dataBindings` maps **service name → prop name → PromQL query**. The dashboard polls each query, applies a transform, and injects the result as a prop on the matched child component.
+
+```ts
+type DataBinding = string | { query: string; transform?: (raw: unknown) => unknown };
+type DataBindings = Record<string, Record<string, DataBinding>>;
+```
+
+- Bare string → uses global `dataTransform` (defaults to numeric parsing)
+- Object `{ query, transform }` → uses per-binding transform
+- Service name key must match child's `name` prop **exactly**
+
+```tsx
+const dataBindings: DataBindings = {
+    "My Service": {
+        cpuLoad: 'cpu_usage{instance="srv-01"}', // bare string → number
+        memLoad: 'memory_usage{instance="srv-01"}', // bare string → number
+        status: {
+            // object → custom transform
+            query: 'cpu_usage{instance="srv-01"}',
+            transform: (raw) => {
+                const n = Number(raw);
+                if (n >= 85) return "critical";
+                if (n >= 70) return "warning";
+                return "online";
+            },
+        },
+        dbCapacity: 'disk_capacity{instance="db-01"}',
+        dbStatus: { query: 'disk_capacity{instance="db-01"}', transform: statusFromValue },
+    },
+};
+```
+
+#### Multi-component services
+
+When a service has multiple nodes of the same type (e.g. three servers), use a flat naming convention with prefixes. Each `DataBinding` maps **one prop → one query** — there is no array or object binding type.
+
+```tsx
+interface ServiceXProps {
+    name: string;
+    status?: ComponentStatus;
+    srv1CpuLoad?: number;
+    srv1MemLoad?: number;
+    srv1Status?: ComponentStatus;
+    srv2CpuLoad?: number;
+    srv2MemLoad?: number;
+    srv2Status?: ComponentStatus;
+    srv3CpuLoad?: number;
+    srv3MemLoad?: number;
+    srv3Status?: ComponentStatus;
+    dbCapacity?: number;
+    dbStatus?: ComponentStatus;
+}
+
+function ServiceX({
+    name, status = "online",
+    srv1CpuLoad = 54, srv1MemLoad = 58, srv1Status = "online",
+    srv2CpuLoad = 63, srv2MemLoad = 66, srv2Status = "online",
+    srv3CpuLoad = 78, srv3MemLoad = 71, srv3Status = "online",
+    dbCapacity = 68, dbStatus = "online",
+}: ServiceXProps) {
+    return (
+        <Service name={name} status={status} connections={[/* ... */]}>
+            <ServerNode name="SRV-X1" status={srv1Status}
+                cpuLoad={srv1CpuLoad} memLoad={srv1MemLoad} ... />
+            <ServerNode name="SRV-X2" status={srv2Status}
+                cpuLoad={srv2CpuLoad} memLoad={srv2MemLoad} ... />
+            <ServerNode name="SRV-X3" status={srv3Status}
+                cpuLoad={srv3CpuLoad} memLoad={srv3MemLoad} ... />
+            <DatabaseNode name="DB-X1" status={dbStatus}
+                capacity={dbCapacity} ... />
+        </Service>
+    );
+}
+```
+
+Bind each prefixed prop individually:
+
+```tsx
+dataBindings={{
+    ServiceX: {
+        status: { query: 'status{instance="svcx"}', transform: statusFromValue },
+        srv1CpuLoad: 'cpu_usage{instance="srvx-01"}',
+        srv1MemLoad: 'memory_usage{instance="srvx-01"}',
+        srv1Status: { query: 'status{instance="srvx-01"}', transform: statusFromValue },
+        srv2CpuLoad: 'cpu_usage{instance="srvx-02"}',
+        srv2MemLoad: 'memory_usage{instance="srvx-02"}',
+        srv2Status: { query: 'status{instance="srvx-02"}', transform: statusFromValue },
+        srv3CpuLoad: 'cpu_usage{instance="srvx-03"}',
+        srv3MemLoad: 'memory_usage{instance="srvx-03"}',
+        srv3Status: { query: 'status{instance="srvx-03"}', transform: statusFromValue },
+        dbCapacity: 'disk_capacity{instance="dbx-01"}',
+        dbStatus: { query: 'status{instance="dbx-01"}', transform: statusFromValue },
+    },
+}}
+```
+
+Use a consistent convention like `srv1CpuLoad`, `srv2CpuLoad`. The service component maps each prefixed prop to the correct node.
+
+### 2. Service dialog — static ServiceMeta metrics
+
+The **ServiceDialog** panel shows KPIs when a service is expanded. Static metrics are passed 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" },
+        ],
+    },
+];
+```
+
+### 3. Service dialog — live serviceDataBindings
+
+Replace static metrics with live-fetched values using `serviceDataBindings`:
+
+```tsx
+serviceDataBindings={{
+    "My Service": [
+        { label: "CPU Load", query: 'cpu_usage{instance="srv-01"}', unit: "%", color: "#00e5ff" },
+        { label: "Memory", query: 'memory_usage{instance="srv-01"}', unit: "%", color: "#bb55ff" },
+        { label: "Disk", query: 'disk_capacity{instance="db-01"}', unit: "%", color: "#ff8c00" },
+    ],
+}}
+```
+
+```ts
+interface ServiceMetricBinding {
+    label: string; // Row label
+    query: string; // PromQL query
+    unit?: string; // Suffix (e.g. "%", "ms")
+    color?: string; // Accent color
+    transform?: (raw: unknown) => string; // Custom formatter
+}
+```
+
+When provided, live values **replace** static `ServiceMeta.metrics` for that service.
+
+### 4. 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.
+
+### 5. Component dialog — 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`.
+
+**Live component dialog metrics pattern**: To feed live query values into custom gauges, expose each metric as a prop on your service component. Use `dataBindings` to inject them. Then build the `dialogMetrics` array from those props:
+
+```tsx
+// Service component — accepts individual metric props, builds dialogMetrics from them
+function MyService({ name, status = "online", cpuLoad = 42, memLoad = 60, iops = 20 }: any) {
+    return (
+        <Service
+            name={name}
+            status={status}
+            connections={
+                [
+                    /* ... */
+                ]
+            }
+        >
+            <ServerNode
+                name="SRV-01"
+                status={status}
+                cpuLoad={cpuLoad}
+                memLoad={memLoad}
+                ex={200}
+                ey={380}
+                compactOffset={{ x: -30, y: -20 }}
+                zIndex={8}
+                dialogMetrics={[
+                    { id: "cpu", label: "CPU", sublabel: "PROCESSOR", value: cpuLoad },
+                    { id: "mem", label: "MEMORY", sublabel: "HEAP", value: memLoad },
+                    {
+                        id: "iops",
+                        label: "IOPS",
+                        sublabel: "DISK OPS",
+                        value: iops,
+                        icon: "disk",
+                        warnAt: 50,
+                        critAt: 80,
+                    },
+                ]}
+            />
+        </Service>
+    );
+}
+
+// Dashboard — bind each prop to a query
+<AIOPsDashboard
+    liveData
+    dataEndpoint="..."
+    dataBindings={{
+        "My Service": {
+            cpuLoad: 'cpu_usage{instance="srv-01"}',
+            memLoad: 'memory_usage{instance="srv-01"}',
+            iops: 'disk_iops{instance="srv-01"}',
+            status: { query: 'cpu_usage{instance="srv-01"}', transform: statusFromValue },
+        },
+    }}
+>
+    <MyService name="My Service" />
+</AIOPsDashboard>;
+```
+
+The dashboard injects `cpuLoad`, `memLoad`, `iops` as live props → they flow into `dialogMetrics` → gauges update automatically on every poll. Works for any number of custom metrics.
+
+### 6. 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 at 67 because critAt=75
+    ]}
+    alert={{ offsetX: -160, offsetY: -60, align: "left" }}
+    ... />
+```
+
+Alert `align` options: `"left"`, `"right"`, `"top"`, `"bottom"`.
+
+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
+}
+```
+
+### 7. 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`.
+
+### 8. 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`.
+
+### 9. Data hooks — programmatic access
+
+Access live data context anywhere inside the dashboard:
+
+```tsx
+import { useAIOpsData, useAIOpsDataOptional, useQueryResult } from "react-dashstream";
+
+function CustomWidget() {
+    const { data, isRefreshing, lastRefreshError, lastRefreshTime, credentialsSet } = useAIOpsData();
+    const cpu = useQueryResult('cpu_usage{instance="srv-01"}');
+    return <div>CPU: {String(cpu)}</div>;
+}
+```
+
+| Hook                     | Returns                    | Throws?                      |
+| ------------------------ | -------------------------- | ---------------------------- |
+| `useAIOpsData()`         | `DataContextValue`         | Yes — outside `DataProvider` |
+| `useAIOpsDataOptional()` | `DataContextValue \| null` | No                           |
+| `useQueryResult(query)`  | `unknown \| null`          | Yes — outside `DataProvider` |
+
+```ts
+interface DataContextValue {
+    data: Record<string, unknown>; // Raw responses keyed by query
+    isRefreshing: boolean;
+    lastRefreshError: string | null;
+    lastRefreshTime: Date | null;
+    credentialsSet: boolean;
+    setCredentials: (creds: Credentials) => void;
+}
+```
+
+---
+
+## 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`, `defaultDataTransform`
+
+### Theme
+
+`STATUS_CFG`, `HOLO_CYAN` (`"#00e5ff"`), `HOLO_BLUE` (`"#0055cc"`), `HOLO_SURFACE`, `HOLO_GLASS`, `makeFaceStyles(W, H, D)`
+
+### Context hooks
+
+`CarouselContext`, `CarouselItemContext`, `useCarouselContext`, `useCarouselItemContext`, `ServiceContext`
+
+### Type exports
+
+`AIOPsDashboardProps`, `ServiceMeta`, `ServiceMetricBinding`, `ComponentStatus`, `StatusCfg`, `FaceName`, `Base3DProps`, `ComponentType`, `ComponentContext`, `ComponentDialogMetric`, `SubComponentConfig`, `GraphSeries`, `SelectedComponent`, `ConnectionConfig`, `ViewState`, `DataBinding`, `DataBindings`, `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`
+
+---
+
+## Key types quick reference
+
+### AIOPsDashboardProps
+
+```ts
+interface AIOPsDashboardProps {
+    title?: string;
+    brandName?: string; // Default: "BUSAUD AIOps"
+    brandTag?: string; // Default: "3D MONITOR"
+    services?: ServiceMeta[];
+    backgroundImage?: string;
+    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[]>;
+    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"
+}
+```
+
+### ComponentStatus
+
+```ts
+type ComponentStatus = "online" | "warning" | "critical" | "offline";
+```
+
+| Status     | Color     | Glow     |
+| ---------- | --------- | -------- |
+| `online`   | `#00e5ff` | cyan     |
+| `warning`  | `#ff8c00` | orange   |
+| `critical` | `#ff2255` | red      |
+| `offline`  | `#1e3a5a` | dim blue |
+
+---
+
+## Endpoint contract
+
+| Aspect       | Requirement                                                    |
+| ------------ | -------------------------------------------------------------- |
+| **Method**   | `GET`                                                          |
+| **URL**      | `<dataEndpoint>?query=<urlEncodedQuery>`                       |
+| **Headers**  | `access-key` and `access-secret-key`                           |
+| **Response** | Plain text body (trimmed). Default transform parses as number. |
+| **Errors**   | Non-2xx → counted as failure per query                         |
+
+For JSON responses, provide a custom `dataTransform`:
+
+```tsx
+dataTransform={(raw) => {
+    const parsed = JSON.parse(String(raw));
+    return parsed?.data?.result?.[0]?.value?.[1] ?? raw;
+}}
+```
+
+---
+
+## Standalone DataProvider
+
+Use the data layer without `AIOPsDashboard`:
+
+```tsx
+import { DataProvider, useAIOpsData } from "react-dashstream";
+
+<DataProvider
+    config={{
+        endpoint: "https://prometheus.example.com/api/v1/query",
+        queries: ['cpu_usage{instance="srv-01"}'],
+        refreshInterval: 15000,
+    }}
+>
+    <MyContent />
+</DataProvider>;
+```
+
+---
+
+## Node positioning guide
+
+The topology scene is ~660×640 pixels.
+
+| Layer       | Typical `ey` | `visibleAtPhase` | Component           |
+| ----------- | ------------ | ---------------- | ------------------- |
+| Users (top) | 100          | 2                | `HumanNode`         |
+| Dispatcher  | 230          | 2                | `WebDispatcherNode` |
+| App servers | 350–380      | 3                | `ServerNode`        |
+| Databases   | 500–520      | 4                | `DatabaseNode`      |
+
+Center X = `330`. Left/right columns: `200` / `460`. Three-column: `165` / `330` / `495`.
+
+`compactOffset` controls node position in the compact carousel view relative to center.
+
+---
+
+## Usage patterns
+
+### Minimal static dashboard
+
+```tsx
+import "react-dashstream/dist/index.css";
+import { AIOPsDashboard, Service, ServerNode, DatabaseNode } from "react-dashstream";
+
+<AIOPsDashboard brandName="MY DASHBOARD" services={[{ name: "Svc", status: "online" }]}>
+    <Service
+        name="Svc"
+        status="online"
+        connections={[{ from: [330, 200], to: [330, 380], visibleAtPhase: 3 }]}
+    >
+        <ServerNode
+            ex={330}
+            ey={380}
+            compactOffset={{ x: 0, y: 0 }}
+            zIndex={8}
+            name="SRV-01"
+            status="online"
+            cpuLoad={42}
+            memLoad={60}
+        />
+    </Service>
+</AIOPsDashboard>;
+```
+
+### Full live-data dashboard
+
+```tsx
+<AIOPsDashboard
+    brandName="LIVE MONITOR"
+    services={services}
+    liveData={true}
+    dataEndpoint="https://prometheus.example.com/api/v1/query"
+    dataRefreshInterval={10000}
+    dataBindings={{
+        "My Service": {
+            cpuLoad: 'cpu_usage{instance="srv-01"}',
+            status: { query: 'cpu_usage{instance="srv-01"}', transform: statusFromValue },
+        },
+    }}
+    serviceDataBindings={{
+        "My Service": [{ label: "CPU", query: 'cpu_usage{instance="srv-01"}', unit: "%", color: "#00e5ff" }],
+    }}
+>
+    <MyService name="My Service" />
+</AIOPsDashboard>
+```
+
+### Custom service with all data features
+
+```tsx
+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>
+    );
+}
+```
+
+---
+
+## 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.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "react-dashstream",
-    "version": "0.0.8",
+    "version": "0.0.9",
     "type": "module",
     "author": "Busaud",
     "license": "MIT",
@@ -15,7 +15,8 @@
     ],
     "files": [
         "dist",
-        "README.md"
+        "README.md",
+        "dashstream-skill.md"
     ],
     "main": "./dist/index.js",
     "module": "./dist/index.js",