react-dashstream 0.2.0 → 0.3.1

package/dashstream-skill.md

@@ -1,1062 +1,1208 @@
-# React DashStream — AI Coding Assistant Skill
-
-> **Package**: `react-dashstream` (npm)
-> **Version**: 0.2.0
-> **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.
-
----
-
-## 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)
-```
-
-### 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 (filter, sort, search, infinite scroll)
-│   │   ├── EventView.css           # Holographic table styles
-│   │   ├── EventAlertsContext.tsx   # EventAlertsProvider + per-host alert map
-│   │   ├── fetchEvents.ts          # Shared fetch/mapping logic (used by both EventView & provider)
-│   │   ├── types.ts                # AIOpsEvent, EventSeverity, EventApiConfig, etc.
-│   │   ├── mockData.ts             # 28 realistic mock events
-│   │   └── index.ts
-│   └── index.ts
-├── services/
-│   ├── SAPService.tsx, ExchangeService.tsx
-│   ├── sapSubComponents.tsx
-│   └── index.ts
-example/
-├── Dashboard.tsx
-└── services/
-```
-
----
-
-## Complete data flow reference
-
-There are **10 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. Event-to-dashboard bridge — automatic node alerts from events API
-
-When `eventApiConfig` is passed to `AIOPsDashboard`, events are fetched in the background and nodes whose `name` (case-insensitive) matches an event `host` automatically show alert callouts.
-
-```tsx
-<AIOPsDashboard
-    eventApiConfig={eventApiConfig} // same EventApiConfig used for EventView
-    liveData
-    dataEndpoint="..."
-    dataBindings={dataBindings}
-    services={services}
->
-    <MyService name="My Service" />
-</AIOPsDashboard>
-```
-
-**How it works internally:**
-
-1. `AIOPsDashboard` wraps children in `EventAlertsProvider` (inside `DataProvider` when `liveData` is set — shares credentials automatically)
-2. `EventAlertsProvider` fetches events using the same `fetchEvents` + `mapRawEvent` logic as `EventView`
-3. Events are grouped by **lower-cased hostname** into a `Map<string, EventHostAlert>`
-4. `ServiceNode` reads from `EventAlertsContext` via `useEventAlertsOptional()`
-5. If `componentInfo.name.toLowerCase()` matches an entry, event severity is factored into the existing `resolveNodeSeverity` pipeline as a **third severity source** (alongside node status and metric breaches)
-6. Highest severity among all three sources wins
-7. `NodeCallout` appears automatically with the event message; multi-event hosts show `"N events – message"`
-
-**Severity mapping:**
-
-| Event severity | → ComponentStatus |
-| -------------- | ----------------- |
-| Critical       | `"critical"`      |
-| Major          | `"warning"`       |
-| Minor          | `"warning"`       |
-
-**Key requirement:** Node `name` props must match event `host` values from the API (case-insensitive). Example: if the API returns `host: "SAP-PRD-APP01"`, the node must be `<ServerNode name="SAP-PRD-APP01" ... />`.
-
-**Credential resolution order** (for EventAlertsProvider inside AIOPsDashboard):
-
-1. `DataProvider` context credentials (when `liveData` is enabled — same credentials, one login)
-2. Built-in `CredentialsModal` (when `liveData` is not enabled)
-
-**Opt-in:** Without `eventApiConfig`, no events are fetched — zero overhead.
-
-**When generating an `AIOPsDashboard` with event bridge:** Reuse the same `EventApiConfig` object that the user already has for their `EventView`. Just add it as `eventApiConfig` on `AIOPsDashboard`.
-
-### 8. 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`.
-
-### 9. 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`.
-
-### 10. 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`
-
-### 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`, `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`
-
----
-
-## Key types quick reference
-
-### 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"
-}
-```
-
-### 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>
-    );
-}
-```
-
----
-
-## EventView — Operations Event Console
-
-Table component for displaying infrastructure events from a live API. Uses the same `access-key` / `access-secret-key` authentication and holographic theme as the 3D dashboard. No built-in default data — requires either `apiConfig` (to fetch from an API) or `events` (pre-fetched array).
-
-### API mode (primary usage)
-
-```tsx
-import "react-dashstream/dist/index.css";
-import { EventView } from "react-dashstream";
-import type { EventApiConfig } from "react-dashstream";
-
-const apiConfig: EventApiConfig = {
-    baseUrl: "https://your-monitoring-server.example.com",
-    payload: { filter: {}, sortBy: "date_reception", sortOrder: "DESC" },
-    fieldMapping: {
-        id: "mc_ueid",
-        occurrence: "date_reception",
-        severityLastModified: "severity_last_modified",
-        severity: "severity",
-        owner: "owner",
-        class: "class",
-        host: "mc_host",
-        message: "msg",
-        remedySupportGroup: "ara_remedy_support_group",
-        incidentId: "ara_incident_id",
-        smsStatus: "ara_sms_status",
-        onCallNumber: "ara_on_call_number",
-        hostedApplication: "ara_hosted_application",
-        monitoringCategory: "ara_hosted_app_monitoring",
-        applicationSupportUnit: "ara_application_support_unit",
-    },
-};
-
-<EventView apiConfig={apiConfig} />;
-```
-
-### How it works
-
-1. Shows credentials modal (or reuses DataProvider credentials if inside `AIOPsDashboard`)
-2. Sends `POST {baseUrl}/tsws/monitoring/api/v1.0/events/search` with the payload as JSON body
-3. Auth via headers: `access-key` and `access-secret-key`
-4. Expects response: `{ eventSeverityCount: {...}, totalCount: N, eventList: [{...}] }`
-5. Maps each object in `eventList` to `AIOpsEvent` using `fieldMapping`
-6. Maps severity strings via `severityMap` (default: `CRITICAL→Critical`, `MAJOR→Major`, `MINOR→Minor`)
-7. Polls on `refreshInterval` (default 60s)
-
-### Props
-
-| Prop                 | Type             | Default           | Notes                                              |
-| -------------------- | ---------------- | ----------------- | -------------------------------------------------- |
-| `apiConfig`          | `EventApiConfig` | —                 | Required for API mode                              |
-| `events`             | `AIOpsEvent[]`   | —                 | Pre-fetched events (skips API calls)               |
-| `credentials`        | `Credentials`    | —                 | Explicit creds; falls back to DataProvider → modal |
-| `columnWidthsCookie` | `string`         | `"ev_col_widths"` | Cookie name for persisting column widths           |
-| `title`              | `string`         | `"Event Console"` | Header title                                       |
-| `theme`              | `DashboardTheme` | —                 | Optional override; else `ThemeProvider` / default  |
-
-### EventApiConfig
-
-```ts
-interface EventApiConfig {
-    baseUrl: string; // "https://monitoring.example.com"
-    endpoint?: string; // default: "/tsws/monitoring/api/v1.0/events/search"
-    payload: Record<string, unknown>; // POST body
-    fieldMapping: EventFieldMapping; // maps API keys → AIOpsEvent keys
-    severityMap?: Record<string, EventSeverity>; // default: { CRITICAL, MAJOR, MINOR }
-    refreshInterval?: number; // ms, default 60000
-}
-```
-
-### EventFieldMapping
-
-Maps every `AIOpsEvent` property to the API response field name. All 15 keys required:
-
-```ts
-type EventFieldMapping = Record<keyof AIOpsEvent, string>;
-```
-
-### AIOpsEvent interface
-
-```ts
-interface AIOpsEvent {
-    id: string;
-    occurrence: string;
-    severityLastModified: string;
-    severity: "Minor" | "Major" | "Critical";
-    owner: string;
-    class: "Self-monitoring" | "SCOM" | "Situation" | "Alarm" | "Event";
-    host: string;
-    message: string;
-    remedySupportGroup: string;
-    incidentId: string;
-    smsStatus: "" | "SUCCESS" | "FAILED";
-    onCallNumber: string;
-    hostedApplication: string;
-    monitoringCategory: "24/7" | "Office Hours";
-    applicationSupportUnit: string;
-}
-```
-
-### Credential resolution order
-
-1. `credentials` prop (if provided)
-2. `DataProvider` context credentials (when inside `AIOPsDashboard` with `liveData`)
-3. Built-in credentials modal (same UI as the 3D dashboard)
-
-### Severity colors
-
-- **Minor** → `#ffb800` (amber)
-- **Major** → `#ff6600` (orange)
-- **Critical** → `#ff2255` (red)
-
-### Features
-
-- Live API polling with configurable interval and manual refresh button
-- Configurable field mapping — any API response shape can be mapped
-- Shared auth — reuses DataProvider credentials when available
-- Severity filter chips with live counts
-- Free-text search across message, host, owner, incident ID
-- Sortable columns (click header: asc → desc → none)
-- Infinite scroll — all matching events in a single scrollable table
-- Resizable columns — drag column edges; widths persist in cookies
-- Loading spinner, error badge, last-refresh timestamp
-- Light / dark table chrome (via `ThemeProvider` or `theme` prop), scan-line header, severity badges
-
-### Generating an EventApiConfig from the AI
-
-When asked to set up EventView for a new API, generate the config like this:
-
-1. Set `baseUrl` to the server's protocol + host + port
-2. Set `endpoint` only if it differs from the default `/tsws/monitoring/api/v1.0/events/search`
-3. Build `payload` based on the API's expected POST body schema
-4. Build `fieldMapping` by asking the user which API field maps to each `AIOpsEvent` property
-5. Set `severityMap` only if the API uses non-standard severity values
-
----
-
-## 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.
+# React DashStream — AI Coding Assistant Skill
+
+> **Package**: `react-dashstream` (npm)
+> **Version**: 0.2.0
+> **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.
+
+---
+
+## 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 (filter, sort, search, infinite scroll)
+│   │   ├── EventView.css           # Holographic table styles
+│   │   ├── EventAlertsContext.tsx   # EventAlertsProvider + per-host alert map
+│   │   ├── fetchEvents.ts          # Shared fetch/mapping logic (used by both EventView & provider)
+│   │   ├── types.ts                # AIOpsEvent, EventSeverity, EventApiConfig, etc.
+│   │   ├── mockData.ts             # 28 realistic mock events
+│   │   └── index.ts
+│   ├── DatacenterView/             # Topology map + CSS 3D building markers
+│   │   ├── DatacenterView.tsx
+│   │   ├── DatacenterView.css
+│   │   ├── buildings.tsx           # DatacenterSite, TowerDC, FlatDC, … (declarative JSX)
+│   │   ├── collectDatacenterTree.ts
+│   │   ├── types.ts
+│   │   └── index.ts
+│   └── index.ts
+├── services/
+│   ├── SAPService.tsx, ExchangeService.tsx
+│   ├── sapSubComponents.tsx
+│   └── index.ts
+example/
+├── Dashboard.tsx
+└── services/
+```
+
+---
+
+## Complete data flow reference
+
+There are **10 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. Event-to-dashboard bridge — automatic node alerts from events API
+
+When `eventApiConfig` is passed to `AIOPsDashboard`, events are fetched in the background and nodes whose `name` (case-insensitive) matches an event `host` automatically show alert callouts.
+
+```tsx
+<AIOPsDashboard
+    eventApiConfig={eventApiConfig} // same EventApiConfig used for EventView
+    liveData
+    dataEndpoint="..."
+    dataBindings={dataBindings}
+    services={services}
+>
+    <MyService name="My Service" />
+</AIOPsDashboard>
+```
+
+**How it works internally:**
+
+1. `AIOPsDashboard` wraps children in `EventAlertsProvider` (inside `DataProvider` when `liveData` is set — shares credentials automatically)
+2. `EventAlertsProvider` fetches events using the same `fetchEvents` + `mapRawEvent` logic as `EventView`
+3. Events are grouped by **lower-cased hostname** into a `Map<string, EventHostAlert>`
+4. `ServiceNode` reads from `EventAlertsContext` via `useEventAlertsOptional()`
+5. If `componentInfo.name.toLowerCase()` matches an entry, event severity is factored into the existing `resolveNodeSeverity` pipeline as a **third severity source** (alongside node status and metric breaches)
+6. Highest severity among all three sources wins
+7. `NodeCallout` appears automatically with the event message; multi-event hosts show `"N events – message"`
+
+**Severity mapping:**
+
+| Event severity | → ComponentStatus |
+| -------------- | ----------------- |
+| Critical       | `"critical"`      |
+| Major          | `"warning"`       |
+| Minor          | `"warning"`       |
+
+**Key requirement:** Node `name` props must match event `host` values from the API (case-insensitive). Example: if the API returns `host: "SAP-PRD-APP01"`, the node must be `<ServerNode name="SAP-PRD-APP01" ... />`.
+
+**Credential resolution order** (for EventAlertsProvider inside AIOPsDashboard):
+
+1. `DataProvider` context credentials (when `liveData` is enabled — same credentials, one login)
+2. Built-in `CredentialsModal` (when `liveData` is not enabled)
+
+**Opt-in:** Without `eventApiConfig`, no events are fetched — zero overhead.
+
+**When generating an `AIOPsDashboard` with event bridge:** Reuse the same `EventApiConfig` object that the user already has for their `EventView`. Just add it as `eventApiConfig` on `AIOPsDashboard`.
+
+### 8. 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`.
+
+### 9. 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`.
+
+### 10. 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`, `extractUniqueQueries`, `extractDatacenterMetricQueries`, `defaultDataTransform`
+
+### Datacenter topology map
+
+`DatacenterView` — plus `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
+
+### 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"
+}
+```
+
+### 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>
+    );
+}
+```
+
+---
+
+## DatacenterView — topology / geography map
+
+SVG-based **network topology** (grid) or optional **geographic outline** (consumer-supplied SVG path `d`), CSS **3D building** markers, animated links, and **drill-down** into a nested `AIOPsDashboard` when the user selects a site or building.
+
+### Data model
+
+- **`DatacenterBuildingConfig`** — one marker on the map (`id`, `name`, `subtitle`, `x` / `y` as **percent** of the 800×600 scene, `status`, `metrics`, `services`, `renderServices`, `variant`, optional `brand`, `isExternal`).
+- **`siteId`** — optional; multiple buildings with the same `siteId` share **one marker**, **combined metrics** (sums / averages for PUE, temperature, uptime), and a **multi-building cluster** visualization (each building’s `variant` is shown). Optional **`siteLabels`** (`Record<string, { label: string; subtitle?: string }>`) overrides auto-generated titles. **`DatacenterSite`** can supply `label` / `subtitle` per `siteId`; the **`siteLabels`** prop merges on top (prop wins on conflict).
+
+### Declarative JSX topology (optional)
+
+Instead of a **`dataCenters`** array, pass **`children`** using **`DatacenterSite`** (coordinates + optional site titles) and one shape component per building: **`StandardDC`**, **`TowerDC`**, **`FlatDC`**, **`StorageDC`**, **`GoogleDC`**, **`MicroDC`**, or **`OfficeDC`** (alias of `MicroDC`). Use **`Datacenter`** with **`variant`** when you want a single generic component. Building components render **`null`** on the map; **`children`** on each building are the drill-down **`Service`** tree (same as `renderServices()` in the array API). **`collectDatacenterTree(children)`** is available if you need the resolved **`DatacenterBuildingConfig[]`** outside the view.
+- **`DatacenterConnection`** — `from` / `to` endpoint ids (building `id` or `siteId`), `throughput` label, optional `isExternal`.
+- **`DatacenterMetrics`** — numeric KPIs used on markers and for aggregation.
+
+### Mock metrics
+
+Pass **`dataCenters`** with embedded **`metrics`**. No `DataProvider` required.
+
+### PromQL (live) metrics on markers
+
+1. Wrap the tree in **`DataProvider`** with `config.queries` including every query used by **`metricBindings`**, collected via **`extractDatacenterMetricQueries(metricBindings)`** (and merge with queries for any nested `AIOPsDashboard` if you use `aiOpsDashboardProps`).
+2. Pass **`metricBindings`**: `Record<buildingId, Partial<Record<keyof DatacenterMetrics, DataBinding>>>` — same **`DataBinding`** shape as service-level bindings (`string` or `{ query, transform? }`).
+3. **`DatacenterView`** calls **`useAIOpsDataOptional()`** and merges transformed numbers over each building’s static `metrics` (site-level rows aggregate the merged per-building values).
+
+This path is **independent** of `AIOPsDashboard`’s **`dataBindings`** (which key off **service `name`** on carousel children).
+
+### Drill-down dashboard
+
+**`aiOpsDashboardProps`** is spread onto the inner **`AIOPsDashboard`**; **`services`**, **`theme`**, **`children`** (from `renderServices()`), and branding are forced from the selected building so the map stays consistent. Use **`aiOpsDashboardProps`** for **`liveData`**, **`dataEndpoint`**, **`dataBindings`**, **`serviceDataBindings`**, etc., for **service-level** PromQL inside the opened datacenter.
+
+### Geography (optional)
+
+**`showGeography`** and **`geography: { outlinePathD, referencePoints? }`** — the package does **not** ship country assets; the app parses or provides an SVG path `d` string (see `example/SaudiMapView.tsx`).
+
+### DatacenterViewProps (reference)
+
+| Prop | Type | Default | Notes |
+|------|------|---------|--------|
+| `children` | `ReactNode` | — | Declarative topology (`DatacenterSite`, `TowerDC`, …). When set, **`dataCenters` is ignored** (dev warning if both are passed) |
+| `dataCenters` | `DatacenterBuildingConfig[]` | `[]` | Flat / JSON-friendly config; required for topology unless **`children`** is used |
+| `connections` | `DatacenterConnection[]` | `[]` | Link lines between building or site ids |
+| `metricBindings` | `DatacenterMetricBindings` | — | Building **id** → metric field → PromQL `DataBinding`; needs `DataProvider` + `extractDatacenterMetricQueries` |
+| `dataTransform` | `(raw: unknown) => unknown` | `defaultDataTransform` | Applied to each binding unless overridden per binding |
+| `geography` | `DatacenterGeography` | — | `outlinePathD` + optional `referencePoints` (SVG coords) |
+| `showGeography` | `boolean` | `false` | When true, draws outline + reference points |
+| `mapTitle` | `string` | `"Geography — Operations"` | Header when `showGeography` |
+| `topologyTitle` | `string` | `"Network topology"` | Header when not showing geography |
+| `topologyAffiliatesLabel` | `string` | `"AFFILIATES"` | Label in topology-only mode (affiliates zone) |
+| `brandText` | `string` | `"AIOps"` | Header brand |
+| `headerTag` | `string` | `"COMMAND CENTER"` | Corner tag |
+| `initialBuildingId` | `string` | — | Building `id` to open when `openDashboardOnMount` is true |
+| `openDashboardOnMount` | `boolean` | `false` | Auto-zoom into `initialBuildingId` |
+| `onNavigateEvents` | `() => void` | — | e.g. switch app view to event console |
+| `theme` | `DashboardTheme` | — | Passed through to drill-down dashboard |
+| `onThemeChange` | `(t) => void` | — | |
+| `backgroundImage` / `lightBackgroundImage` | `string` | — | Drill-down `AIOPsDashboard` backgrounds |
+| `aiOpsDashboardProps` | `Partial<AIOPsDashboardProps>` | — | Spread first; `services`, children, theme, branding overridden from selection |
+| `defaultBuildingBrand` | `string` | `"AIOps"` | Fallback label on 3D building faces |
+| `siteLabels` | `Record<string, DatacenterSiteLabels>` | — | Per-`siteId` titles for multi-building markers |
+| `showMapScaleControls` | `boolean` | `true` | Size / hover sliders in header (map mode) |
+| `mapFooter` | `ReactNode` | — | Rendered below the map when drill-down is **not** active |
+
+### Minimal usage (array config)
+
+```tsx
+import "react-dashstream/dist/index.css";
+import { DatacenterView } from "react-dashstream";
+import type { DatacenterBuildingConfig, DatacenterConnection } from "react-dashstream";
+
+const dataCenters: DatacenterBuildingConfig[] = [
+    /* id, x, y (%), metrics, services, renderServices, variant, siteId? … */
+];
+const connections: DatacenterConnection[] = [];
+
+<DatacenterView dataCenters={dataCenters} connections={connections} />;
+```
+
+### JSX composition (same runtime behavior)
+
+```tsx
+import "react-dashstream/dist/index.css";
+import {
+    DatacenterView,
+    DatacenterSite,
+    TowerDC,
+    FlatDC,
+} from "react-dashstream";
+
+<DatacenterView connections={[]}>
+    <DatacenterSite siteId="riyadh-hub" x={42} y={38} label="Riyadh hub" subtitle="Primary region">
+        <TowerDC
+            id="dc-east-1"
+            name="East tower"
+            subtitle="Tier III"
+            status="online"
+            metrics={{
+                carbonEmissions: 0,
+                powerUtilization: 0,
+                cooling: 0,
+                pue: 1.4,
+                uptime: 99.9,
+                activeServers: 0,
+                temperature: 22,
+                networkThroughput: 0,
+            }}
+            services={[]}
+        >
+            {/* Service / ServerNode / … drill-down tree */}
+        </TowerDC>
+        <FlatDC
+            id="dc-flat-2"
+            name="Flat block"
+            subtitle="Storage"
+            status="online"
+            metrics={{
+                carbonEmissions: 0,
+                powerUtilization: 0,
+                cooling: 0,
+                pue: 1.3,
+                uptime: 99.5,
+                activeServers: 0,
+                temperature: 21,
+                networkThroughput: 0,
+            }}
+            services={[]}
+        />
+    </DatacenterSite>
+</DatacenterView>;
+```
+
+---
+
+## EventView — Operations Event Console
+
+Table component for displaying infrastructure events from a live API. Uses the same `access-key` / `access-secret-key` authentication and holographic theme as the 3D dashboard. No built-in default data — requires either `apiConfig` (to fetch from an API) or `events` (pre-fetched array).
+
+### API mode (primary usage)
+
+```tsx
+import "react-dashstream/dist/index.css";
+import { EventView } from "react-dashstream";
+import type { EventApiConfig } from "react-dashstream";
+
+const apiConfig: EventApiConfig = {
+    baseUrl: "https://your-monitoring-server.example.com",
+    payload: { filter: {}, sortBy: "date_reception", sortOrder: "DESC" },
+    fieldMapping: {
+        id: "mc_ueid",
+        occurrence: "date_reception",
+        severityLastModified: "severity_last_modified",
+        severity: "severity",
+        owner: "owner",
+        class: "class",
+        host: "mc_host",
+        message: "msg",
+        remedySupportGroup: "ara_remedy_support_group",
+        incidentId: "ara_incident_id",
+        smsStatus: "ara_sms_status",
+        onCallNumber: "ara_on_call_number",
+        hostedApplication: "ara_hosted_application",
+        monitoringCategory: "ara_hosted_app_monitoring",
+        applicationSupportUnit: "ara_application_support_unit",
+    },
+};
+
+<EventView apiConfig={apiConfig} />;
+```
+
+### How it works
+
+1. Shows credentials modal (or reuses DataProvider credentials if inside `AIOPsDashboard`)
+2. Sends `POST {baseUrl}/tsws/monitoring/api/v1.0/events/search` with the payload as JSON body
+3. Auth via headers: `access-key` and `access-secret-key`
+4. Expects response: `{ eventSeverityCount: {...}, totalCount: N, eventList: [{...}] }`
+5. Maps each object in `eventList` to `AIOpsEvent` using `fieldMapping`
+6. Maps severity strings via `severityMap` (default: `CRITICAL→Critical`, `MAJOR→Major`, `MINOR→Minor`)
+7. Polls on `refreshInterval` (default 60s)
+
+### Props
+
+| Prop                 | Type             | Default           | Notes                                              |
+| -------------------- | ---------------- | ----------------- | -------------------------------------------------- |
+| `apiConfig`          | `EventApiConfig` | —                 | Required for API mode                              |
+| `events`             | `AIOpsEvent[]`   | —                 | Pre-fetched events (skips API calls)               |
+| `credentials`        | `Credentials`    | —                 | Explicit creds; falls back to DataProvider → modal |
+| `columnWidthsCookie` | `string`         | `"ev_col_widths"` | Cookie name for persisting column widths           |
+| `title`              | `string`         | `"Event Console"` | Header title                                       |
+| `theme`              | `DashboardTheme` | —                 | Optional override; else `ThemeProvider` / default  |
+
+### EventApiConfig
+
+```ts
+interface EventApiConfig {
+    baseUrl: string; // "https://monitoring.example.com"
+    endpoint?: string; // default: "/tsws/monitoring/api/v1.0/events/search"
+    payload: Record<string, unknown>; // POST body
+    fieldMapping: EventFieldMapping; // maps API keys → AIOpsEvent keys
+    severityMap?: Record<string, EventSeverity>; // default: { CRITICAL, MAJOR, MINOR }
+    refreshInterval?: number; // ms, default 60000
+}
+```
+
+### EventFieldMapping
+
+Maps every `AIOpsEvent` property to the API response field name. All 15 keys required:
+
+```ts
+type EventFieldMapping = Record<keyof AIOpsEvent, string>;
+```
+
+### AIOpsEvent interface
+
+```ts
+interface AIOpsEvent {
+    id: string;
+    occurrence: string;
+    severityLastModified: string;
+    severity: "Minor" | "Major" | "Critical";
+    owner: string;
+    class: "Self-monitoring" | "SCOM" | "Situation" | "Alarm" | "Event";
+    host: string;
+    message: string;
+    remedySupportGroup: string;
+    incidentId: string;
+    smsStatus: "" | "SUCCESS" | "FAILED";
+    onCallNumber: string;
+    hostedApplication: string;
+    monitoringCategory: "24/7" | "Office Hours";
+    applicationSupportUnit: string;
+}
+```
+
+### Credential resolution order
+
+1. `credentials` prop (if provided)
+2. `DataProvider` context credentials (when inside `AIOPsDashboard` with `liveData`)
+3. Built-in credentials modal (same UI as the 3D dashboard)
+
+### Severity colors
+
+- **Minor** → `#ffb800` (amber)
+- **Major** → `#ff6600` (orange)
+- **Critical** → `#ff2255` (red)
+
+### Features
+
+- Live API polling with configurable interval and manual refresh button
+- Configurable field mapping — any API response shape can be mapped
+- Shared auth — reuses DataProvider credentials when available
+- Severity filter chips with live counts
+- Free-text search across message, host, owner, incident ID
+- Sortable columns (click header: asc → desc → none)
+- Infinite scroll — all matching events in a single scrollable table
+- Resizable columns — drag column edges; widths persist in cookies
+- Loading spinner, error badge, last-refresh timestamp
+- Light / dark table chrome (via `ThemeProvider` or `theme` prop), scan-line header, severity badges
+
+### Generating an EventApiConfig from the AI
+
+When asked to set up EventView for a new API, generate the config like this:
+
+1. Set `baseUrl` to the server's protocol + host + port
+2. Set `endpoint` only if it differs from the default `/tsws/monitoring/api/v1.0/events/search`
+3. Build `payload` based on the API's expected POST body schema
+4. Build `fieldMapping` by asking the user which API field maps to each `AIOpsEvent` property
+5. Set `severityMap` only if the API uses non-standard severity values
+
+---
+
+## 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.