@principal-ai/storybook-addon-otel 0.1.0

package/README.md

@@ -0,0 +1,220 @@
+# @principal-ai/storybook-addon-otel
+
+Capture and visualize OpenTelemetry data from Storybook story interactions.
+
+## Features
+
+- 📊 **Timeline View**: See all spans and events in chronological order
+- 🎨 **Canvas View**: Visualize telemetry flow on an interactive canvas (coming soon)
+- 📤 **Export**: Download telemetry as JSON for analysis
+- 🔄 **Real-time**: Updates as you interact with stories
+- 🎯 **Automatic**: Wraps stories with telemetry collection
+
+## Installation
+
+```bash
+npm install @principal-ai/storybook-addon-otel --save-dev
+# or
+yarn add @principal-ai/storybook-addon-otel --dev
+# or
+pnpm add @principal-ai/storybook-addon-otel --save-dev
+```
+
+## Setup
+
+### 1. Register the Addon
+
+Add the addon to your `.storybook/main.js` or `.storybook/main.ts`:
+
+```typescript
+import type { StorybookConfig } from '@storybook/react-vite';
+
+const config: StorybookConfig = {
+  addons: [
+    // ... other addons
+    '@principal-ai/storybook-addon-otel',
+  ],
+};
+
+export default config;
+```
+
+### 2. Start Storybook
+
+```bash
+npm run storybook
+```
+
+### 3. View Telemetry
+
+1. Open any story
+2. Look for the **"OTEL Telemetry"** panel at the bottom (next to Actions, Controls, etc.)
+3. Interact with your story to see telemetry captured in real-time
+
+## Usage
+
+### Automatic Telemetry
+
+By default, the addon automatically captures:
+- Story mount/unmount events
+- Story metadata (title, name, id)
+
+### Manual Instrumentation
+
+For custom telemetry, import and use the `TelemetryCollector`:
+
+```typescript
+import { TelemetryCollector } from '@principal-ai/storybook-addon-otel/preview';
+
+export const MyStory = () => {
+  const handleClick = () => {
+    // Create a span
+    const span = TelemetryCollector.startSpan('button-click');
+
+    // Add an event
+    TelemetryCollector.addEvent(span, 'clicked', {
+      'button.id': 'submit',
+      'button.text': 'Submit',
+    });
+
+    // End the span
+    TelemetryCollector.endSpan(span);
+  };
+
+  return <button onClick={handleClick}>Click me</button>;
+};
+```
+
+### Instrumenting Event Emitters
+
+```typescript
+import { TelemetryCollector } from '@principal-ai/storybook-addon-otel/preview';
+
+// Wrap your event emitter
+const originalEmit = events.emit.bind(events);
+events.emit = (event) => {
+  const span = TelemetryCollector.startSpan(event.type);
+  TelemetryCollector.addEvent(span, event.type, event.payload);
+  TelemetryCollector.endSpan(span);
+  return originalEmit(event);
+};
+```
+
+### Disabling Telemetry for Specific Stories
+
+```typescript
+export default {
+  title: 'My Story',
+  parameters: {
+    otelTelemetry: {
+      enabled: false, // Disable for this story
+    },
+  },
+};
+```
+
+## API Reference
+
+### `TelemetryCollector`
+
+#### `startSpan(name, attributes?, parentId?)`
+Create a new telemetry span.
+
+**Parameters:**
+- `name` (string): Name of the span
+- `attributes` (object, optional): Key-value pairs of span attributes
+- `parentId` (string, optional): ID of parent span for hierarchical spans
+
+**Returns:** TelemetrySpan object
+
+#### `addEvent(span, eventName, attributes?)`
+Add an event to a span.
+
+**Parameters:**
+- `span` (TelemetrySpan): The span to add the event to
+- `eventName` (string): Name of the event
+- `attributes` (object, optional): Key-value pairs of event attributes
+
+#### `endSpan(span)`
+End a span and calculate its duration.
+
+**Parameters:**
+- `span` (TelemetrySpan): The span to end
+
+#### `getSpans()`
+Get all collected spans.
+
+**Returns:** Array of TelemetrySpan objects
+
+#### `clear()`
+Clear all collected telemetry.
+
+## Panel Features
+
+### Timeline View
+- Shows all spans chronologically
+- Displays span names, durations, and status
+- Shows attributes and events for each span
+- Color-coded by status (OK = green, ERROR = red)
+
+### Canvas View (Coming Soon)
+- Visual representation of execution flow
+- Interactive graph showing span relationships
+- Integrates with Principal View GraphRenderer
+
+### Export
+- Download telemetry as JSON
+- Compatible with OpenTelemetry trace format
+- Can be imported into analysis tools
+
+## Development
+
+### Building
+
+```bash
+npm run build
+```
+
+### Local Development
+
+Link the package locally:
+
+```bash
+cd packages/storybook-addon-otel
+npm link
+
+# In your project
+npm link @principal-ai/storybook-addon-otel
+```
+
+## Examples
+
+See the `examples/` directory for complete examples:
+- Basic telemetry capture
+- Event emitter instrumentation
+- Complex lifecycle tracking
+- Integration with canvas schemas
+
+## Integration with Principal View
+
+This addon is designed to work with the Principal View ecosystem:
+
+- Define event schemas in `.otel.canvas` files
+- Validate captured events against schemas
+- Visualize execution flows on canvas
+- Export telemetry for offline analysis
+
+See the [Principal View documentation](https://github.com/principal-ai/principal-view-core-library) for more information.
+
+## License
+
+MIT
+
+## Contributing
+
+Contributions are welcome! Please see the [contributing guide](../../CONTRIBUTING.md).
+
+## Support
+
+- [GitHub Issues](https://github.com/principal-ai/principal-view-core-library/issues)
+- [Documentation](https://github.com/principal-ai/principal-view-core-library/tree/main/packages/storybook-addon-otel)

package/dist/collector.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Telemetry Collector
+ *
+ * Captures spans and events during story interactions
+ */
+export interface SpanEvent {
+    time: number;
+    name: string;
+    attributes: Record<string, string | number | boolean>;
+}
+export interface TelemetrySpan {
+    id: string;
+    name: string;
+    parentId?: string;
+    startTime: number;
+    endTime?: number;
+    duration?: number;
+    attributes: Record<string, string | number | boolean>;
+    events: SpanEvent[];
+    status: 'OK' | 'ERROR';
+    errorMessage?: string;
+}
+declare class TelemetryCollectorImpl {
+    private spans;
+    private spanIdCounter;
+    private activeSpans;
+    private channel;
+    constructor();
+    startSpan(name: string, attributes?: Record<string, string | number | boolean>, parentId?: string): TelemetrySpan;
+    addEvent(span: TelemetrySpan, eventName: string, attributes?: Record<string, string | number | boolean>): void;
+    endSpan(span: TelemetrySpan): void;
+    markError(span: TelemetrySpan, error: Error | string): void;
+    getSpans(): TelemetrySpan[];
+    clear(): void;
+    private emit;
+    exportJson(): string;
+}
+export declare const TelemetryCollector: TelemetryCollectorImpl;
+export {};

package/dist/collector.js

@@ -0,0 +1,83 @@
+"use strict";
+/**
+ * Telemetry Collector
+ *
+ * Captures spans and events during story interactions
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TelemetryCollector = void 0;
+const manager_api_1 = require("@storybook/manager-api");
+const constants_1 = require("./constants");
+class TelemetryCollectorImpl {
+    constructor() {
+        this.spans = [];
+        this.spanIdCounter = 0;
+        this.activeSpans = new Map();
+        // Get communication channel with manager
+        if (typeof manager_api_1.addons !== 'undefined') {
+            this.channel = manager_api_1.addons.getChannel();
+        }
+    }
+    startSpan(name, attributes, parentId) {
+        const span = {
+            id: `span-${++this.spanIdCounter}`,
+            name,
+            parentId,
+            startTime: Date.now(),
+            attributes: {
+                'component.name': name,
+                ...attributes,
+            },
+            events: [],
+            status: 'OK',
+        };
+        this.spans.push(span);
+        this.activeSpans.set(span.id, span);
+        console.log('[TelemetryCollector] Started span:', name, 'Total spans:', this.spans.length);
+        this.emit();
+        return span;
+    }
+    addEvent(span, eventName, attributes) {
+        span.events.push({
+            time: Date.now(),
+            name: eventName,
+            attributes: attributes || {},
+        });
+        this.emit();
+    }
+    endSpan(span) {
+        span.endTime = Date.now();
+        span.duration = span.endTime - span.startTime;
+        this.activeSpans.delete(span.id);
+        this.emit();
+    }
+    markError(span, error) {
+        span.status = 'ERROR';
+        span.errorMessage = typeof error === 'string' ? error : error.message;
+        span.attributes['error'] = true;
+        span.attributes['error.message'] = span.errorMessage;
+        this.emit();
+    }
+    getSpans() {
+        return [...this.spans];
+    }
+    clear() {
+        this.spans = [];
+        this.spanIdCounter = 0;
+        this.activeSpans.clear();
+        this.emit();
+    }
+    emit() {
+        console.log('[TelemetryCollector] Emitting update, spans:', this.spans.length, 'has channel:', !!this.channel);
+        if (this.channel) {
+            this.channel.emit(constants_1.EVENTS.TELEMETRY_UPDATE, this.getSpans());
+        }
+    }
+    exportJson() {
+        // End any active spans
+        this.activeSpans.forEach(span => this.endSpan(span));
+        return JSON.stringify(this.spans, null, 2);
+    }
+}
+// Singleton instance
+exports.TelemetryCollector = new TelemetryCollectorImpl();

package/dist/components/TelemetryPanel.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Telemetry Panel Component
+ *
+ * Displays captured telemetry in Storybook panel
+ */
+import React from 'react';
+interface PanelProps {
+    active: boolean;
+}
+export declare const TelemetryPanel: React.FC<PanelProps>;
+export {};

package/dist/components/TelemetryPanel.js

@@ -0,0 +1,235 @@
+"use strict";
+/**
+ * Telemetry Panel Component
+ *
+ * Displays captured telemetry in Storybook panel
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TelemetryPanel = void 0;
+const react_1 = __importStar(require("react"));
+const manager_api_1 = require("@storybook/manager-api");
+const components_1 = require("@storybook/components");
+const theming_1 = require("@storybook/theming");
+const constants_1 = require("../constants");
+const PanelContainer = theming_1.styled.div `
+  padding: 16px;
+  font-family: monospace;
+  font-size: 12px;
+  height: 100%;
+  overflow: auto;
+  background: #1a1a1a;
+  color: #e6e6e6;
+`;
+const Header = theming_1.styled.div `
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  margin-bottom: 16px;
+  padding-bottom: 12px;
+  border-bottom: 1px solid #333;
+`;
+const Button = theming_1.styled.button `
+  background: #3b82f6;
+  color: white;
+  border: none;
+  border-radius: 4px;
+  padding: 6px 12px;
+  cursor: pointer;
+  font-size: 12px;
+  margin-left: 8px;
+
+  &:hover {
+    background: #2563eb;
+  }
+`;
+const SpanCard = theming_1.styled.div `
+  background: #242424;
+  border: 1px solid ${props => props.status === 'ERROR' ? '#ef4444' : '#333'};
+  border-radius: 6px;
+  padding: 12px;
+  margin-bottom: 12px;
+`;
+const SpanHeader = theming_1.styled.div `
+  display: flex;
+  justify-content: space-between;
+  align-items: flex-start;
+  margin-bottom: 8px;
+`;
+const SpanName = theming_1.styled.div `
+  font-weight: 600;
+  color: #3b82f6;
+  font-size: 13px;
+`;
+const SpanDuration = theming_1.styled.div `
+  color: #10b981;
+  font-size: 11px;
+`;
+const Attributes = theming_1.styled.div `
+  margin-top: 8px;
+  padding: 8px;
+  background: #1a1a1a;
+  border-radius: 4px;
+  font-size: 11px;
+`;
+const AttributeRow = theming_1.styled.div `
+  padding: 2px 0;
+  color: #a0a0a0;
+
+  span:first-child {
+    color: #8b5cf6;
+  }
+`;
+const EventList = theming_1.styled.div `
+  margin-top: 8px;
+`;
+const Event = theming_1.styled.div `
+  padding: 6px 8px;
+  background: #1a1a1a;
+  border-left: 2px solid #f59e0b;
+  margin-bottom: 4px;
+  font-size: 11px;
+`;
+const EventName = theming_1.styled.div `
+  color: #f59e0b;
+  font-weight: 600;
+  margin-bottom: 4px;
+`;
+const ViewToggle = theming_1.styled.div `
+  display: flex;
+  gap: 8px;
+  margin-bottom: 16px;
+`;
+const ToggleButton = theming_1.styled.button `
+  background: ${props => props.active ? '#3b82f6' : '#333'};
+  color: ${props => props.active ? 'white' : '#a0a0a0'};
+  border: none;
+  border-radius: 4px;
+  padding: 6px 16px;
+  cursor: pointer;
+  font-size: 12px;
+
+  &:hover {
+    background: ${props => props.active ? '#2563eb' : '#404040'};
+  }
+`;
+const CanvasPlaceholder = theming_1.styled.div `
+  padding: 40px;
+  text-align: center;
+  color: #666;
+  border: 2px dashed #333;
+  border-radius: 8px;
+
+  h3 {
+    margin: 0 0 8px 0;
+    color: #999;
+  }
+
+  p {
+    margin: 0;
+    font-size: 12px;
+  }
+`;
+const TelemetryPanel = ({ active }) => {
+    const [spans, setSpans] = (0, react_1.useState)([]);
+    const [view, setView] = (0, react_1.useState)('timeline');
+    const emit = (0, manager_api_1.useChannel)({
+        [constants_1.EVENTS.TELEMETRY_UPDATE]: (newSpans) => {
+            console.log('[TelemetryPanel] Received update, spans:', newSpans.length, newSpans);
+            setSpans(newSpans);
+        },
+    });
+    console.log('[TelemetryPanel] Render, active:', active, 'spans:', spans.length);
+    const handleClear = () => {
+        emit(constants_1.EVENTS.CLEAR_TELEMETRY);
+        setSpans([]);
+    };
+    const handleExport = () => {
+        const json = JSON.stringify(spans, null, 2);
+        const blob = new Blob([json], { type: 'application/json' });
+        const url = URL.createObjectURL(blob);
+        const a = document.createElement('a');
+        a.href = url;
+        a.download = 'storybook-telemetry.json';
+        a.click();
+        URL.revokeObjectURL(url);
+    };
+    if (!active) {
+        return null;
+    }
+    return (react_1.default.createElement(components_1.AddonPanel, { active: active },
+        react_1.default.createElement(PanelContainer, null,
+            react_1.default.createElement(Header, null,
+                react_1.default.createElement("div", null,
+                    react_1.default.createElement("strong", null, "OTEL Telemetry"),
+                    react_1.default.createElement("div", { style: { fontSize: '11px', color: '#666', marginTop: '4px' } },
+                        spans.length,
+                        " span",
+                        spans.length !== 1 ? 's' : '',
+                        " collected")),
+                react_1.default.createElement("div", null,
+                    react_1.default.createElement(Button, { onClick: handleClear }, "Clear"),
+                    react_1.default.createElement(Button, { onClick: handleExport }, "Export JSON"))),
+            react_1.default.createElement(ViewToggle, null,
+                react_1.default.createElement(ToggleButton, { active: view === 'timeline', onClick: () => setView('timeline') }, "Timeline"),
+                react_1.default.createElement(ToggleButton, { active: view === 'canvas', onClick: () => setView('canvas') }, "Canvas")),
+            view === 'timeline' ? (react_1.default.createElement(react_1.default.Fragment, null, spans.length === 0 ? (react_1.default.createElement("div", { style: { textAlign: 'center', padding: '40px', color: '#666' } }, "No telemetry data yet. Interact with the story to capture spans.")) : (spans.map(span => (react_1.default.createElement(SpanCard, { key: span.id, status: span.status },
+                react_1.default.createElement(SpanHeader, null,
+                    react_1.default.createElement(SpanName, null, span.name),
+                    span.duration && (react_1.default.createElement(SpanDuration, null,
+                        span.duration,
+                        "ms"))),
+                Object.keys(span.attributes).length > 0 && (react_1.default.createElement(Attributes, null, Object.entries(span.attributes).map(([key, value]) => (react_1.default.createElement(AttributeRow, { key: key },
+                    react_1.default.createElement("span", null,
+                        key,
+                        ":"),
+                    " ",
+                    String(value)))))),
+                span.events.length > 0 && (react_1.default.createElement(EventList, null, span.events.map((event, idx) => (react_1.default.createElement(Event, { key: idx },
+                    react_1.default.createElement(EventName, null, event.name),
+                    Object.entries(event.attributes).map(([key, value]) => (react_1.default.createElement(AttributeRow, { key: key },
+                        react_1.default.createElement("span", null,
+                            key,
+                            ":"),
+                        " ",
+                        String(value))))))))),
+                span.errorMessage && (react_1.default.createElement("div", { style: { marginTop: '8px', color: '#ef4444', fontSize: '11px' } },
+                    "Error: ",
+                    span.errorMessage)))))))) : (react_1.default.createElement(CanvasPlaceholder, null,
+                react_1.default.createElement("h3", null, "Canvas Visualization"),
+                react_1.default.createElement("p", null, "Canvas view will visualize the telemetry flow using your GraphRenderer."),
+                react_1.default.createElement("p", { style: { marginTop: '8px', fontSize: '11px' } }, "To implement: Convert spans to canvas format and render with GraphRenderer"))))));
+};
+exports.TelemetryPanel = TelemetryPanel;

package/dist/constants.d.ts

@@ -0,0 +1,8 @@
+export declare const ADDON_ID = "storybook-addon-otel-telemetry";
+export declare const PANEL_ID = "storybook-addon-otel-telemetry/panel";
+export declare const PARAM_KEY = "otelTelemetry";
+export declare const EVENTS: {
+    TELEMETRY_UPDATE: string;
+    CLEAR_TELEMETRY: string;
+    EXPORT_TELEMETRY: string;
+};

package/dist/constants.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EVENTS = exports.PARAM_KEY = exports.PANEL_ID = exports.ADDON_ID = void 0;
+exports.ADDON_ID = 'storybook-addon-otel-telemetry';
+exports.PANEL_ID = `${exports.ADDON_ID}/panel`;
+exports.PARAM_KEY = 'otelTelemetry';
+exports.EVENTS = {
+    TELEMETRY_UPDATE: `${exports.ADDON_ID}/telemetry-update`,
+    CLEAR_TELEMETRY: `${exports.ADDON_ID}/clear-telemetry`,
+    EXPORT_TELEMETRY: `${exports.ADDON_ID}/export-telemetry`,
+};

package/dist/decorator.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Story Decorator
+ *
+ * Wraps stories to automatically capture telemetry
+ */
+import React from 'react';
+import { TelemetryCollector } from './collector';
+export declare const withTelemetry: (Story: any, context: any) => React.JSX.Element;
+export declare function useTelemetry(): {
+    rootSpan: any;
+    collector: typeof TelemetryCollector;
+};
+export declare function useTelemetrySpan(name: string, attributes?: Record<string, string | number | boolean>, deps?: unknown[]): any;
+export declare const decorators: ((Story: any, context: any) => React.JSX.Element)[];

package/dist/decorator.js

@@ -0,0 +1,104 @@
+"use strict";
+/**
+ * Story Decorator
+ *
+ * Wraps stories to automatically capture telemetry
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.decorators = exports.withTelemetry = void 0;
+exports.useTelemetry = useTelemetry;
+exports.useTelemetrySpan = useTelemetrySpan;
+const react_1 = __importStar(require("react"));
+const collector_1 = require("./collector");
+const constants_1 = require("./constants");
+const withTelemetry = (Story, context) => {
+    const [rootSpan, setRootSpan] = (0, react_1.useState)(null);
+    // Check if telemetry is enabled for this story
+    const enabled = context.parameters[constants_1.PARAM_KEY]?.enabled !== false;
+    console.log('[Telemetry Decorator] Story:', context.title + '/' + context.name, 'Enabled:', enabled);
+    (0, react_1.useEffect)(() => {
+        if (!enabled)
+            return;
+        // Start root span for story
+        const span = collector_1.TelemetryCollector.startSpan(`Story: ${context.title}/${context.name}`, {
+            'story.id': context.id,
+            'story.title': context.title,
+            'story.name': context.name,
+        });
+        setRootSpan(span);
+        collector_1.TelemetryCollector.addEvent(span, 'story.mounted', {
+            'story.name': `${context.title}/${context.name}`,
+        });
+        return () => {
+            collector_1.TelemetryCollector.addEvent(span, 'story.unmounted', {});
+            collector_1.TelemetryCollector.endSpan(span);
+        };
+    }, [context.id, enabled]);
+    if (!enabled) {
+        return react_1.default.createElement(Story, null);
+    }
+    return (react_1.default.createElement(TelemetryProvider, { rootSpan: rootSpan },
+        react_1.default.createElement(Story, null)));
+};
+exports.withTelemetry = withTelemetry;
+// Context to provide telemetry to story components
+const TelemetryContext = react_1.default.createContext(null);
+function TelemetryProvider({ children, rootSpan }) {
+    return (react_1.default.createElement(TelemetryContext.Provider, { value: { rootSpan, collector: collector_1.TelemetryCollector } }, children));
+}
+// Hook for stories to access telemetry
+function useTelemetry() {
+    const context = react_1.default.useContext(TelemetryContext);
+    if (!context) {
+        throw new Error('useTelemetry must be used within a story with telemetry enabled');
+    }
+    return context;
+}
+// Hook for automatic span lifecycle
+function useTelemetrySpan(name, attributes, deps = []) {
+    const { rootSpan } = useTelemetry();
+    const [span, setSpan] = (0, react_1.useState)(null);
+    (0, react_1.useEffect)(() => {
+        const newSpan = collector_1.TelemetryCollector.startSpan(name, attributes, rootSpan?.id);
+        setSpan(newSpan);
+        return () => {
+            collector_1.TelemetryCollector.endSpan(newSpan);
+        };
+    }, deps);
+    return span;
+}
+// Export decorators array for Storybook
+exports.decorators = [exports.withTelemetry];

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Public API exports
+ */
+export { TelemetryCollector } from './collector';
+export { useTelemetry, useTelemetrySpan, withTelemetry } from './decorator';
+export type { TelemetrySpan, SpanEvent } from './collector';

package/dist/index.js

@@ -0,0 +1,12 @@
+"use strict";
+/**
+ * Public API exports
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withTelemetry = exports.useTelemetrySpan = exports.useTelemetry = exports.TelemetryCollector = void 0;
+var collector_1 = require("./collector");
+Object.defineProperty(exports, "TelemetryCollector", { enumerable: true, get: function () { return collector_1.TelemetryCollector; } });
+var decorator_1 = require("./decorator");
+Object.defineProperty(exports, "useTelemetry", { enumerable: true, get: function () { return decorator_1.useTelemetry; } });
+Object.defineProperty(exports, "useTelemetrySpan", { enumerable: true, get: function () { return decorator_1.useTelemetrySpan; } });
+Object.defineProperty(exports, "withTelemetry", { enumerable: true, get: function () { return decorator_1.withTelemetry; } });

package/dist/manager.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Addon Manager Registration
+ *
+ * Registers the telemetry panel in Storybook UI
+ */
+export {};

package/dist/manager.js

@@ -0,0 +1,22 @@
+"use strict";
+/**
+ * Addon Manager Registration
+ *
+ * Registers the telemetry panel in Storybook UI
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const react_1 = __importDefault(require("react"));
+const manager_api_1 = require("@storybook/manager-api");
+const TelemetryPanel_1 = require("./components/TelemetryPanel");
+const constants_1 = require("./constants");
+manager_api_1.addons.register(constants_1.ADDON_ID, (api) => {
+    manager_api_1.addons.add(constants_1.PANEL_ID, {
+        type: manager_api_1.types.PANEL,
+        title: 'OTEL Telemetry',
+        match: ({ viewMode }) => viewMode === 'story',
+        render: ({ active }) => react_1.default.createElement(TelemetryPanel_1.TelemetryPanel, { active: active || false }),
+    });
+});

package/dist/preset.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Addon Preset
+ *
+ * Configures the addon for Storybook
+ */
+export declare function managerEntries(entry?: any[]): any[];
+export declare function previewAnnotations(entry?: any[]): any[];

package/dist/preset.js

@@ -0,0 +1,15 @@
+"use strict";
+/**
+ * Addon Preset
+ *
+ * Configures the addon for Storybook
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.managerEntries = managerEntries;
+exports.previewAnnotations = previewAnnotations;
+function managerEntries(entry = []) {
+    return [...entry, require.resolve('./manager')];
+}
+function previewAnnotations(entry = []) {
+    return [...entry, require.resolve('./decorator')];
+}

package/dist/preview.js

@@ -0,0 +1,121 @@
+/**
+ * Preview-side entry point (runs in browser)
+ * Must be ESM format
+ */
+
+import React, { useEffect, useState } from 'react';
+
+// Simple telemetry collector for browser
+class BrowserTelemetryCollector {
+  constructor() {
+    this.spans = [];
+    this.spanIdCounter = 0;
+    this.activeSpans = new Map();
+
+    // Try to get Storybook channel (might not be available immediately)
+    if (typeof window !== 'undefined' && window.__STORYBOOK_ADDONS_CHANNEL__) {
+      this.channel = window.__STORYBOOK_ADDONS_CHANNEL__;
+    }
+  }
+
+  startSpan(name, attributes = {}, parentId) {
+    const span = {
+      id: `span-${++this.spanIdCounter}`,
+      name,
+      parentId,
+      startTime: Date.now(),
+      attributes: {
+        'component.name': name,
+        ...attributes,
+      },
+      events: [],
+      status: 'OK',
+    };
+
+    this.spans.push(span);
+    this.activeSpans.set(span.id, span);
+
+    console.log('[TelemetryCollector] Started span:', name, 'Total spans:', this.spans.length);
+    this.emit();
+
+    return span;
+  }
+
+  addEvent(span, eventName, attributes = {}) {
+    span.events.push({
+      time: Date.now(),
+      name: eventName,
+      attributes,
+    });
+    this.emit();
+  }
+
+  endSpan(span) {
+    span.endTime = Date.now();
+    span.duration = span.endTime - span.startTime;
+    this.activeSpans.delete(span.id);
+    this.emit();
+  }
+
+  getSpans() {
+    return [...this.spans];
+  }
+
+  clear() {
+    this.spans = [];
+    this.spanIdCounter = 0;
+    this.activeSpans.clear();
+    this.emit();
+  }
+
+  emit() {
+    // Get channel if not already set
+    if (!this.channel && typeof window !== 'undefined' && window.__STORYBOOK_ADDONS_CHANNEL__) {
+      this.channel = window.__STORYBOOK_ADDONS_CHANNEL__;
+    }
+
+    console.log('[TelemetryCollector] Emitting update, spans:', this.spans.length, 'has channel:', !!this.channel);
+
+    if (this.channel) {
+      this.channel.emit('storybook-addon-otel-telemetry/telemetry-update', this.getSpans());
+    }
+  }
+}
+
+// Singleton instance
+const TelemetryCollector = new BrowserTelemetryCollector();
+
+// Decorator
+export const withTelemetry = (Story, context) => {
+  const [rootSpan, setRootSpan] = useState(null);
+
+  console.log('[Telemetry Decorator] Story:', context.title + '/' + context.name);
+
+  useEffect(() => {
+    // Start root span for story
+    const span = TelemetryCollector.startSpan(`Story: ${context.title}/${context.name}`, {
+      'story.id': context.id,
+      'story.title': context.title,
+      'story.name': context.name,
+    });
+
+    setRootSpan(span);
+
+    TelemetryCollector.addEvent(span, 'story.mounted', {
+      'story.name': `${context.title}/${context.name}`,
+    });
+
+    return () => {
+      TelemetryCollector.addEvent(span, 'story.unmounted', {});
+      TelemetryCollector.endSpan(span);
+    };
+  }, [context.id]);
+
+  return React.createElement(Story);
+};
+
+// Export decorators array
+export const decorators = [withTelemetry];
+
+// Export for manual use
+export { TelemetryCollector };

package/manager.js

@@ -0,0 +1,5 @@
+/**
+ * Manager entry point
+ * Re-exports from dist
+ */
+module.exports = require('./dist/manager.js');

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "@principal-ai/storybook-addon-otel",
+  "version": "0.1.0",
+  "description": "Storybook addon for capturing and visualizing OpenTelemetry data from story interactions",
+  "main": "dist/preset.js",
+  "types": "dist/preset.d.ts",
+  "files": [
+    "dist/**/*",
+    "preset.js",
+    "preview.js",
+    "manager.js",
+    "README.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/preset.d.ts",
+      "default": "./preset.js"
+    },
+    "./preset": {
+      "types": "./dist/preset.d.ts",
+      "default": "./preset.js"
+    },
+    "./preview": {
+      "types": "./dist/preview.d.ts",
+      "default": "./preview.js"
+    },
+    "./manager": {
+      "types": "./dist/manager.d.ts",
+      "default": "./dist/manager.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "build": "tsc && node scripts/copy-browser-files.js",
+    "dev": "tsc --watch",
+    "clean": "rm -rf dist"
+  },
+  "keywords": [
+    "storybook",
+    "storybook-addons",
+    "addon",
+    "telemetry",
+    "opentelemetry",
+    "otel",
+    "observability",
+    "visualization",
+    "canvas"
+  ],
+  "author": "Principal AI",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/principal-ai/principal-view-core-library",
+    "directory": "packages/storybook-addon-otel"
+  },
+  "peerDependencies": {
+    "@storybook/components": "^7.0.0 || ^8.0.0",
+    "@storybook/manager-api": "^7.0.0 || ^8.0.0",
+    "@storybook/preview-api": "^7.0.0 || ^8.0.0",
+    "@storybook/theming": "^7.0.0 || ^8.0.0",
+    "react": "^16.8.0 || ^17.0.0 || ^18.0.0",
+    "react-dom": "^16.8.0 || ^17.0.0 || ^18.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "@types/react": "^18.0.0",
+    "typescript": "^5.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/preset.js

@@ -0,0 +1,16 @@
+/**
+ * Storybook Preset
+ * Registers manager and preview entries for the addon
+ */
+
+const path = require('path');
+
+function managerEntries(entry = []) {
+  return [...entry, path.join(__dirname, 'dist', 'manager.js')];
+}
+
+function previewAnnotations(entry = []) {
+  return [...entry, path.join(__dirname, 'preview.js')];
+}
+
+module.exports = { managerEntries, previewAnnotations };

package/preview.js

@@ -0,0 +1,121 @@
+/**
+ * Preview-side entry point (runs in browser)
+ * Must be ESM format
+ */
+
+import React, { useEffect, useState } from 'react';
+
+// Simple telemetry collector for browser
+class BrowserTelemetryCollector {
+  constructor() {
+    this.spans = [];
+    this.spanIdCounter = 0;
+    this.activeSpans = new Map();
+
+    // Try to get Storybook channel (might not be available immediately)
+    if (typeof window !== 'undefined' && window.__STORYBOOK_ADDONS_CHANNEL__) {
+      this.channel = window.__STORYBOOK_ADDONS_CHANNEL__;
+    }
+  }
+
+  startSpan(name, attributes = {}, parentId) {
+    const span = {
+      id: `span-${++this.spanIdCounter}`,
+      name,
+      parentId,
+      startTime: Date.now(),
+      attributes: {
+        'component.name': name,
+        ...attributes,
+      },
+      events: [],
+      status: 'OK',
+    };
+
+    this.spans.push(span);
+    this.activeSpans.set(span.id, span);
+
+    console.log('[TelemetryCollector] Started span:', name, 'Total spans:', this.spans.length);
+    this.emit();
+
+    return span;
+  }
+
+  addEvent(span, eventName, attributes = {}) {
+    span.events.push({
+      time: Date.now(),
+      name: eventName,
+      attributes,
+    });
+    this.emit();
+  }
+
+  endSpan(span) {
+    span.endTime = Date.now();
+    span.duration = span.endTime - span.startTime;
+    this.activeSpans.delete(span.id);
+    this.emit();
+  }
+
+  getSpans() {
+    return [...this.spans];
+  }
+
+  clear() {
+    this.spans = [];
+    this.spanIdCounter = 0;
+    this.activeSpans.clear();
+    this.emit();
+  }
+
+  emit() {
+    // Get channel if not already set
+    if (!this.channel && typeof window !== 'undefined' && window.__STORYBOOK_ADDONS_CHANNEL__) {
+      this.channel = window.__STORYBOOK_ADDONS_CHANNEL__;
+    }
+
+    console.log('[TelemetryCollector] Emitting update, spans:', this.spans.length, 'has channel:', !!this.channel);
+
+    if (this.channel) {
+      this.channel.emit('storybook-addon-otel-telemetry/telemetry-update', this.getSpans());
+    }
+  }
+}
+
+// Singleton instance
+const TelemetryCollector = new BrowserTelemetryCollector();
+
+// Decorator
+export const withTelemetry = (Story, context) => {
+  const [rootSpan, setRootSpan] = useState(null);
+
+  console.log('[Telemetry Decorator] Story:', context.title + '/' + context.name);
+
+  useEffect(() => {
+    // Start root span for story
+    const span = TelemetryCollector.startSpan(`Story: ${context.title}/${context.name}`, {
+      'story.id': context.id,
+      'story.title': context.title,
+      'story.name': context.name,
+    });
+
+    setRootSpan(span);
+
+    TelemetryCollector.addEvent(span, 'story.mounted', {
+      'story.name': `${context.title}/${context.name}`,
+    });
+
+    return () => {
+      TelemetryCollector.addEvent(span, 'story.unmounted', {});
+      TelemetryCollector.endSpan(span);
+    };
+  }, [context.id]);
+
+  return React.createElement(Story);
+};
+
+// Export decorators array
+export const decorators = [withTelemetry];
+
+// Export for manual use
+export { TelemetryCollector };