@principal-ai/subsystems-core 0.29.0

package/dist/storyboard/builder.d.ts

@@ -0,0 +1,135 @@
+/**
+ * Storyboard Context Builder
+ *
+ * Utilities for building StoryboardContextSliceData from canvas and workflow artifacts.
+ * Used by hosts to create the context slice for panels like File City.
+ */
+import type { ExtendedCanvas, ExtendedCanvasNode } from '../types/canvas';
+import type { WorkflowTemplate, WorkflowScenario } from '../workflow/types';
+import type { StoryboardReference, StoryboardContextSliceData } from './types';
+import type { CanvasType } from '../discovery/types';
+/**
+ * Map of event name to canvas node IDs that emit that event.
+ */
+export type EventNodeMap = Map<string, string[]>;
+/**
+ * Options for building storyboard context.
+ */
+export interface BuildStoryboardContextOptions {
+    /** The parsed canvas content */
+    canvas: ExtendedCanvas;
+    /** Storyboard metadata (id, name, path) */
+    storyboard: StoryboardReference;
+    /** Canvas type (defaults to 'otel') */
+    canvasType?: CanvasType;
+    /** Optional: Selected workflow template and its path */
+    workflow?: {
+        template: WorkflowTemplate;
+        path: string;
+    };
+    /** Optional: Selected scenario within the workflow */
+    scenario?: WorkflowScenario;
+    /** Optional: Additional supporting files to include */
+    additionalSupportingFiles?: string[];
+}
+/**
+ * Build a map of event name to canvas node IDs.
+ * Uses `pv.event.name` or `pv.eventRef` from each node.
+ *
+ * @param canvas - The extended canvas with nodes
+ * @returns Map of event names to node IDs that emit those events
+ *
+ * @example
+ * ```typescript
+ * const eventMap = buildEventNodeMap(canvas);
+ * // Map { 'auth.login' => ['node-abc'], 'api.fetch' => ['node-xyz', 'node-def'] }
+ * ```
+ */
+export declare function buildEventNodeMap(canvas: ExtendedCanvas): EventNodeMap;
+/**
+ * Get the event name from a canvas node.
+ *
+ * Supports two schema locations:
+ * 1. Top-level `event.name` / `eventRef` (OtelEventNode in .otel.canvas files)
+ * 2. `pv.event.name` / `pv.eventRef` (PVNodeExtension for generic canvas nodes)
+ *
+ * @param node - The canvas node
+ * @returns Event name or undefined if node doesn't emit events
+ */
+export declare function getNodeEventName(node: ExtendedCanvasNode): string | undefined;
+/**
+ * Resolve workflow scenario event requirements to canvas node IDs.
+ *
+ * Given a scenario's required events, finds which canvas nodes emit those events.
+ *
+ * @param canvas - The extended canvas with nodes
+ * @param scenario - The workflow scenario with event requirements
+ * @returns Array of canvas node IDs involved in this scenario
+ *
+ * @example
+ * ```typescript
+ * const nodeIds = resolveScenarioNodeIds(canvas, scenario);
+ * // ['node-abc', 'node-xyz'] - nodes that emit events required by the scenario
+ * ```
+ */
+export declare function resolveScenarioNodeIds(canvas: ExtendedCanvas, scenario: WorkflowScenario): string[];
+/**
+ * Resolve workflow template to canvas node IDs.
+ *
+ * Returns all unique node IDs that are involved in any scenario of the workflow.
+ *
+ * @param canvas - The extended canvas with nodes
+ * @param workflow - The workflow template with scenarios
+ * @returns Array of canvas node IDs involved in this workflow
+ */
+export declare function resolveWorkflowNodeIds(canvas: ExtendedCanvas, workflow: WorkflowTemplate): string[];
+/**
+ * Find node IDs matching an event pattern (supports glob-style wildcards).
+ *
+ * @param eventMap - Map of event names to node IDs
+ * @param pattern - Event pattern (e.g., "auth.login", "*.error", "api.*")
+ * @returns Array of matching node IDs
+ */
+export declare function findNodesMatchingEventPattern(eventMap: EventNodeMap, pattern: string): string[];
+/**
+ * Get all node IDs from a canvas.
+ * Useful when no specific workflow/scenario is selected (widest scope).
+ *
+ * @param canvas - The extended canvas with nodes
+ * @returns Array of all node IDs in the canvas
+ */
+export declare function getAllNodeIds(canvas: ExtendedCanvas): string[];
+/**
+ * Build a complete StoryboardContextSliceData from canvas and optional workflow/scenario.
+ *
+ * This is the main function for creating the context slice that panels consume.
+ *
+ * @param options - Build options with canvas, storyboard, and optional workflow/scenario
+ * @returns Complete storyboard context slice data
+ *
+ * @example
+ * ```typescript
+ * // Just storyboard selected (widest scope)
+ * const context = buildStoryboardContext({
+ *   canvas: parsedCanvas,
+ *   storyboard: { id: 'checkout-flow', name: 'Checkout Flow', path: 'canvas.otel.canvas' },
+ * });
+ *
+ * // With workflow selected (medium scope)
+ * const context = buildStoryboardContext({
+ *   canvas: parsedCanvas,
+ *   storyboard: { id: 'checkout-flow', name: 'Checkout Flow', path: 'canvas.otel.canvas' },
+ *   workflow: { template: workflowTemplate, path: 'workflow.workflow.json' },
+ * });
+ *
+ * // With scenario selected (narrowest scope)
+ * const context = buildStoryboardContext({
+ *   canvas: parsedCanvas,
+ *   storyboard: { id: 'checkout-flow', name: 'Checkout Flow', path: 'canvas.otel.canvas' },
+ *   workflow: { template: workflowTemplate, path: 'workflow.workflow.json' },
+ *   scenario: selectedScenario,
+ * });
+ * ```
+ */
+export declare function buildStoryboardContext(options: BuildStoryboardContextOptions): StoryboardContextSliceData;
+//# sourceMappingURL=builder.d.ts.map

package/dist/storyboard/builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"builder.d.ts","sourceRoot":"","sources":["../../src/storyboard/builder.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAE1E,OAAO,KAAK,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAC5E,OAAO,KAAK,EACV,mBAAmB,EAGnB,0BAA0B,EAC3B,MAAM,SAAS,CAAC;AACjB,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAOrD;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;AAEjD;;GAEG;AACH,MAAM,WAAW,6BAA6B;IAC5C,gCAAgC;IAChC,MAAM,EAAE,cAAc,CAAC;IAEvB,2CAA2C;IAC3C,UAAU,EAAE,mBAAmB,CAAC;IAEhC,uCAAuC;IACvC,UAAU,CAAC,EAAE,UAAU,CAAC;IAExB,wDAAwD;IACxD,QAAQ,CAAC,EAAE;QACT,QAAQ,EAAE,gBAAgB,CAAC;QAC3B,IAAI,EAAE,MAAM,CAAC;KACd,CAAC;IAEF,sDAAsD;IACtD,QAAQ,CAAC,EAAE,gBAAgB,CAAC;IAE5B,uDAAuD;IACvD,yBAAyB,CAAC,EAAE,MAAM,EAAE,CAAC;CACtC;AAMD;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,cAAc,GAAG,YAAY,CAiBtE;AAED;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,kBAAkB,GAAG,MAAM,GAAG,SAAS,CAgB7E;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,cAAc,EACtB,QAAQ,EAAE,gBAAgB,GACzB,MAAM,EAAE,CAgBV;AAED;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,cAAc,EACtB,QAAQ,EAAE,gBAAgB,GACzB,MAAM,EAAE,CAWV;AAED;;;;;;GAMG;AACH,wBAAgB,6BAA6B,CAC3C,QAAQ,EAAE,YAAY,EACtB,OAAO,EAAE,MAAM,GACd,MAAM,EAAE,CAiBV;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,cAAc,GAAG,MAAM,EAAE,CAK9D;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,6BAA6B,GACrC,0BAA0B,CA+C5B"}

package/dist/storyboard/builder.js

@@ -0,0 +1,235 @@
+"use strict";
+/**
+ * Storyboard Context Builder
+ *
+ * Utilities for building StoryboardContextSliceData from canvas and workflow artifacts.
+ * Used by hosts to create the context slice for panels like File City.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildStoryboardContext = exports.getAllNodeIds = exports.findNodesMatchingEventPattern = exports.resolveWorkflowNodeIds = exports.resolveScenarioNodeIds = exports.getNodeEventName = exports.buildEventNodeMap = void 0;
+const canvas_1 = require("../types/canvas");
+const CanvasFileManifest_1 = require("../discovery/CanvasFileManifest");
+// ============================================================================
+// Core Functions
+// ============================================================================
+/**
+ * Build a map of event name to canvas node IDs.
+ * Uses `pv.event.name` or `pv.eventRef` from each node.
+ *
+ * @param canvas - The extended canvas with nodes
+ * @returns Map of event names to node IDs that emit those events
+ *
+ * @example
+ * ```typescript
+ * const eventMap = buildEventNodeMap(canvas);
+ * // Map { 'auth.login' => ['node-abc'], 'api.fetch' => ['node-xyz', 'node-def'] }
+ * ```
+ */
+function buildEventNodeMap(canvas) {
+    const eventMap = new Map();
+    if (!canvas.nodes) {
+        return eventMap;
+    }
+    for (const node of canvas.nodes) {
+        const eventName = getNodeEventName(node);
+        if (eventName) {
+            const existing = eventMap.get(eventName) || [];
+            existing.push(node.id);
+            eventMap.set(eventName, existing);
+        }
+    }
+    return eventMap;
+}
+exports.buildEventNodeMap = buildEventNodeMap;
+/**
+ * Get the event name from a canvas node.
+ *
+ * Supports two schema locations:
+ * 1. Top-level `event.name` / `eventRef` (OtelEventNode in .otel.canvas files)
+ * 2. `pv.event.name` / `pv.eventRef` (PVNodeExtension for generic canvas nodes)
+ *
+ * @param node - The canvas node
+ * @returns Event name or undefined if node doesn't emit events
+ */
+function getNodeEventName(node) {
+    // 1. Top-level OtelEventNode format (newer .otel.canvas files)
+    const topLevelEvent = node.event?.name;
+    if (topLevelEvent)
+        return topLevelEvent;
+    // Check OTEL event node (top-level event/eventRef)
+    if ((0, canvas_1.isOtelEventNode)(node)) {
+        return node.event?.name || node.eventRef;
+    }
+    // Check standard node with pv.event/pv.eventRef
+    if ((0, canvas_1.isStandardCanvasNode)(node)) {
+        return node.pv?.event?.name || node.pv?.eventRef;
+    }
+    return undefined;
+}
+exports.getNodeEventName = getNodeEventName;
+/**
+ * Resolve workflow scenario event requirements to canvas node IDs.
+ *
+ * Given a scenario's required events, finds which canvas nodes emit those events.
+ *
+ * @param canvas - The extended canvas with nodes
+ * @param scenario - The workflow scenario with event requirements
+ * @returns Array of canvas node IDs involved in this scenario
+ *
+ * @example
+ * ```typescript
+ * const nodeIds = resolveScenarioNodeIds(canvas, scenario);
+ * // ['node-abc', 'node-xyz'] - nodes that emit events required by the scenario
+ * ```
+ */
+function resolveScenarioNodeIds(canvas, scenario) {
+    const eventMap = buildEventNodeMap(canvas);
+    const nodeIds = new Set();
+    // Get required events from scenario template.events
+    const requiredEvents = Object.keys(scenario.template?.events || {});
+    for (const eventPattern of requiredEvents) {
+        // Handle glob patterns (e.g., "*.error", "auth.*")
+        const matchingNodes = findNodesMatchingEventPattern(eventMap, eventPattern);
+        for (const nodeId of matchingNodes) {
+            nodeIds.add(nodeId);
+        }
+    }
+    return Array.from(nodeIds);
+}
+exports.resolveScenarioNodeIds = resolveScenarioNodeIds;
+/**
+ * Resolve workflow template to canvas node IDs.
+ *
+ * Returns all unique node IDs that are involved in any scenario of the workflow.
+ *
+ * @param canvas - The extended canvas with nodes
+ * @param workflow - The workflow template with scenarios
+ * @returns Array of canvas node IDs involved in this workflow
+ */
+function resolveWorkflowNodeIds(canvas, workflow) {
+    const nodeIds = new Set();
+    for (const scenario of workflow.scenarios) {
+        const scenarioNodeIds = resolveScenarioNodeIds(canvas, scenario);
+        for (const nodeId of scenarioNodeIds) {
+            nodeIds.add(nodeId);
+        }
+    }
+    return Array.from(nodeIds);
+}
+exports.resolveWorkflowNodeIds = resolveWorkflowNodeIds;
+/**
+ * Find node IDs matching an event pattern (supports glob-style wildcards).
+ *
+ * @param eventMap - Map of event names to node IDs
+ * @param pattern - Event pattern (e.g., "auth.login", "*.error", "api.*")
+ * @returns Array of matching node IDs
+ */
+function findNodesMatchingEventPattern(eventMap, pattern) {
+    const matchingNodes = [];
+    // Simple glob matching
+    const regexPattern = pattern
+        .replace(/\./g, '\\.') // Escape dots
+        .replace(/\*/g, '.*'); // Convert * to .*
+    const regex = new RegExp(`^${regexPattern}$`);
+    for (const [eventName, nodeIds] of eventMap) {
+        if (regex.test(eventName)) {
+            matchingNodes.push(...nodeIds);
+        }
+    }
+    return matchingNodes;
+}
+exports.findNodesMatchingEventPattern = findNodesMatchingEventPattern;
+/**
+ * Get all node IDs from a canvas.
+ * Useful when no specific workflow/scenario is selected (widest scope).
+ *
+ * @param canvas - The extended canvas with nodes
+ * @returns Array of all node IDs in the canvas
+ */
+function getAllNodeIds(canvas) {
+    if (!canvas.nodes) {
+        return [];
+    }
+    return canvas.nodes.map((node) => node.id);
+}
+exports.getAllNodeIds = getAllNodeIds;
+// ============================================================================
+// Context Builder
+// ============================================================================
+/**
+ * Build a complete StoryboardContextSliceData from canvas and optional workflow/scenario.
+ *
+ * This is the main function for creating the context slice that panels consume.
+ *
+ * @param options - Build options with canvas, storyboard, and optional workflow/scenario
+ * @returns Complete storyboard context slice data
+ *
+ * @example
+ * ```typescript
+ * // Just storyboard selected (widest scope)
+ * const context = buildStoryboardContext({
+ *   canvas: parsedCanvas,
+ *   storyboard: { id: 'checkout-flow', name: 'Checkout Flow', path: 'canvas.otel.canvas' },
+ * });
+ *
+ * // With workflow selected (medium scope)
+ * const context = buildStoryboardContext({
+ *   canvas: parsedCanvas,
+ *   storyboard: { id: 'checkout-flow', name: 'Checkout Flow', path: 'canvas.otel.canvas' },
+ *   workflow: { template: workflowTemplate, path: 'workflow.workflow.json' },
+ * });
+ *
+ * // With scenario selected (narrowest scope)
+ * const context = buildStoryboardContext({
+ *   canvas: parsedCanvas,
+ *   storyboard: { id: 'checkout-flow', name: 'Checkout Flow', path: 'canvas.otel.canvas' },
+ *   workflow: { template: workflowTemplate, path: 'workflow.workflow.json' },
+ *   scenario: selectedScenario,
+ * });
+ * ```
+ */
+function buildStoryboardContext(options) {
+    const { canvas, storyboard, canvasType = 'otel', workflow, scenario, additionalSupportingFiles = [] } = options;
+    // Build canvas file manifest
+    const manifest = (0, CanvasFileManifest_1.buildCanvasFileManifest)(canvas, storyboard.id, storyboard.path, canvasType);
+    // Build supporting files list
+    const supportingFiles = [storyboard.path];
+    if (workflow) {
+        supportingFiles.push(workflow.path);
+    }
+    // Add markdown doc if canvas has one
+    if (canvas.markdown) {
+        supportingFiles.push(canvas.markdown);
+    }
+    supportingFiles.push(...additionalSupportingFiles);
+    // Determine workflow reference
+    let workflowReference = null;
+    if (workflow) {
+        const workflowNodeIds = resolveWorkflowNodeIds(canvas, workflow.template);
+        workflowReference = {
+            id: `${storyboard.id}/${workflow.template.name.toLowerCase().replace(/\s+/g, '-')}`,
+            name: workflow.template.name,
+            path: workflow.path,
+            nodeIds: workflowNodeIds,
+        };
+    }
+    // Determine scenario reference
+    let scenarioReference = null;
+    if (scenario) {
+        const scenarioNodeIds = resolveScenarioNodeIds(canvas, scenario);
+        scenarioReference = {
+            id: scenario.id,
+            name: scenario.description,
+            nodeIds: scenarioNodeIds,
+        };
+    }
+    return {
+        storyboard,
+        workflow: workflowReference,
+        scenario: scenarioReference,
+        manifest,
+        supportingFiles,
+    };
+}
+exports.buildStoryboardContext = buildStoryboardContext;
+//# sourceMappingURL=builder.js.map

package/dist/storyboard/builder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"builder.js","sourceRoot":"","sources":["../../src/storyboard/builder.ts"],"names":[],"mappings":"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"}

package/dist/storyboard/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Storyboard Context Module
+ *
+ * Types and utilities for building storyboard context data that panels consume.
+ */
+export type { StoryboardReference, WorkflowReference, ScenarioReference, StoryboardContextSliceData, } from './types';
+export { buildStoryboardContext, buildEventNodeMap, getNodeEventName, resolveScenarioNodeIds, resolveWorkflowNodeIds, findNodesMatchingEventPattern, getAllNodeIds, } from './builder';
+export type { EventNodeMap, BuildStoryboardContextOptions } from './builder';
+//# sourceMappingURL=index.d.ts.map

package/dist/storyboard/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/storyboard/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,YAAY,EACV,mBAAmB,EACnB,iBAAiB,EACjB,iBAAiB,EACjB,0BAA0B,GAC3B,MAAM,SAAS,CAAC;AAGjB,OAAO,EACL,sBAAsB,EACtB,iBAAiB,EACjB,gBAAgB,EAChB,sBAAsB,EACtB,sBAAsB,EACtB,6BAA6B,EAC7B,aAAa,GACd,MAAM,WAAW,CAAC;AAEnB,YAAY,EAAE,YAAY,EAAE,6BAA6B,EAAE,MAAM,WAAW,CAAC"}

package/dist/storyboard/index.js

@@ -0,0 +1,18 @@
+"use strict";
+/**
+ * Storyboard Context Module
+ *
+ * Types and utilities for building storyboard context data that panels consume.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getAllNodeIds = exports.findNodesMatchingEventPattern = exports.resolveWorkflowNodeIds = exports.resolveScenarioNodeIds = exports.getNodeEventName = exports.buildEventNodeMap = exports.buildStoryboardContext = void 0;
+// Builder utilities
+var builder_1 = require("./builder");
+Object.defineProperty(exports, "buildStoryboardContext", { enumerable: true, get: function () { return builder_1.buildStoryboardContext; } });
+Object.defineProperty(exports, "buildEventNodeMap", { enumerable: true, get: function () { return builder_1.buildEventNodeMap; } });
+Object.defineProperty(exports, "getNodeEventName", { enumerable: true, get: function () { return builder_1.getNodeEventName; } });
+Object.defineProperty(exports, "resolveScenarioNodeIds", { enumerable: true, get: function () { return builder_1.resolveScenarioNodeIds; } });
+Object.defineProperty(exports, "resolveWorkflowNodeIds", { enumerable: true, get: function () { return builder_1.resolveWorkflowNodeIds; } });
+Object.defineProperty(exports, "findNodesMatchingEventPattern", { enumerable: true, get: function () { return builder_1.findNodesMatchingEventPattern; } });
+Object.defineProperty(exports, "getAllNodeIds", { enumerable: true, get: function () { return builder_1.getAllNodeIds; } });
+//# sourceMappingURL=index.js.map

package/dist/storyboard/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/storyboard/index.ts"],"names":[],"mappings":";AAAA;;;;GAIG;;;AAUH,oBAAoB;AACpB,qCAQmB;AAPjB,iHAAA,sBAAsB,OAAA;AACtB,4GAAA,iBAAiB,OAAA;AACjB,2GAAA,gBAAgB,OAAA;AAChB,iHAAA,sBAAsB,OAAA;AACtB,iHAAA,sBAAsB,OAAA;AACtB,wHAAA,6BAA6B,OAAA;AAC7B,wGAAA,aAAa,OAAA"}

package/dist/storyboard/types.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Storyboard Context Types
+ *
+ * Types for representing storyboard context data that panels consume.
+ * Used to communicate which storyboard/workflow/scenario is selected
+ * and provide file manifests for visualization.
+ */
+import type { CanvasFileManifest } from '../discovery/types';
+/**
+ * Reference to a storyboard (canvas) in the storyboard context.
+ * Represents the top-level selection in the storyboard hierarchy.
+ */
+export interface StoryboardReference {
+    /** Unique storyboard identifier (e.g., "core/checkout-flow") */
+    id: string;
+    /** Display name (e.g., "Checkout Flow") */
+    name: string;
+    /** Path to the canvas file (e.g., ".principal-views/checkout-flow.otel.canvas") */
+    path: string;
+}
+/**
+ * Reference to a workflow within a storyboard.
+ * Workflows define a subset of nodes from the parent canvas.
+ */
+export interface WorkflowReference {
+    /** Unique workflow identifier (e.g., "core/checkout-flow/complete-checkout") */
+    id: string;
+    /** Display name (e.g., "Complete Checkout") */
+    name: string;
+    /** Path to the workflow file (e.g., ".principal-views/checkout-flow/complete-checkout.workflow.json") */
+    path: string;
+    /** Canvas node IDs involved in this workflow (resolved from event requirements) */
+    nodeIds: string[];
+}
+/**
+ * Reference to a scenario within a workflow.
+ * Scenarios represent specific execution paths through a workflow.
+ */
+export interface ScenarioReference {
+    /** Unique scenario identifier (e.g., "payment-success") */
+    id: string;
+    /** Display name (e.g., "Payment Success") */
+    name: string;
+    /** Canvas node IDs involved in this scenario (subset of workflow nodes) */
+    nodeIds: string[];
+}
+/**
+ * Storyboard context slice data.
+ *
+ * Provides context about the currently selected storyboard, workflow, and scenario.
+ * Used by panels (like File City) to highlight files associated with the selection.
+ *
+ * Hierarchy: Storyboard → Workflow → Scenario
+ * - 1 Storyboard = 1 Canvas
+ * - Workflows contain a subset of nodes from the canvas
+ * - Scenarios contain a subset of nodes from their parent workflow
+ *
+ * @example
+ * ```typescript
+ * const storyboardContext: StoryboardContextSliceData = {
+ *   storyboard: {
+ *     id: 'checkout-flow',
+ *     name: 'Checkout Flow',
+ *     path: '.principal-views/checkout-flow.otel.canvas',
+ *   },
+ *   workflow: {
+ *     id: 'checkout-flow/complete-checkout',
+ *     name: 'Complete Checkout',
+ *     path: '.principal-views/checkout-flow/complete-checkout.workflow.json',
+ *     nodeIds: ['node-cart', 'node-payment', 'node-confirm'],
+ *   },
+ *   scenario: null,
+ *   manifest: { ... }, // CanvasFileManifest with file mappings
+ *   supportingFiles: [
+ *     '.principal-views/checkout-flow.otel.canvas',
+ *     '.principal-views/checkout-flow/complete-checkout.workflow.json',
+ *   ],
+ * };
+ * ```
+ */
+export interface StoryboardContextSliceData {
+    /** Currently selected storyboard (1 storyboard = 1 canvas) */
+    storyboard: StoryboardReference | null;
+    /** Currently selected workflow (optional, narrower scope than storyboard) */
+    workflow: WorkflowReference | null;
+    /** Currently selected scenario (optional, narrowest scope) */
+    scenario: ScenarioReference | null;
+    /**
+     * Canvas file manifest with bidirectional mappings.
+     * Use `manifest.nodeToFiles.get(nodeId)` to get files for a node.
+     * Use `manifest.fileToNodes.get(path)` to get nodes for a file.
+     * Use `manifest.byRole.instrumentation` for instrumented files.
+     */
+    manifest: CanvasFileManifest | null;
+    /**
+     * Additional files associated with the storyboard context.
+     * Includes canvas files, workflow definitions, and related documentation.
+     */
+    supportingFiles: string[];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/storyboard/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/storyboard/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAM7D;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAClC,gEAAgE;IAChE,EAAE,EAAE,MAAM,CAAC;IACX,2CAA2C;IAC3C,IAAI,EAAE,MAAM,CAAC;IACb,mFAAmF;IACnF,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC,gFAAgF;IAChF,EAAE,EAAE,MAAM,CAAC;IACX,+CAA+C;IAC/C,IAAI,EAAE,MAAM,CAAC;IACb,yGAAyG;IACzG,IAAI,EAAE,MAAM,CAAC;IACb,mFAAmF;IACnF,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC,2DAA2D;IAC3D,EAAE,EAAE,MAAM,CAAC;IACX,6CAA6C;IAC7C,IAAI,EAAE,MAAM,CAAC;IACb,2EAA2E;IAC3E,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,MAAM,WAAW,0BAA0B;IACzC,8DAA8D;IAC9D,UAAU,EAAE,mBAAmB,GAAG,IAAI,CAAC;IAEvC,6EAA6E;IAC7E,QAAQ,EAAE,iBAAiB,GAAG,IAAI,CAAC;IAEnC,8DAA8D;IAC9D,QAAQ,EAAE,iBAAiB,GAAG,IAAI,CAAC;IAEnC;;;;;OAKG;IACH,QAAQ,EAAE,kBAAkB,GAAG,IAAI,CAAC;IAEpC;;;OAGG;IACH,eAAe,EAAE,MAAM,EAAE,CAAC;CAC3B"}

package/dist/storyboard/types.js

@@ -0,0 +1,10 @@
+"use strict";
+/**
+ * Storyboard Context Types
+ *
+ * Types for representing storyboard context data that panels consume.
+ * Used to communicate which storyboard/workflow/scenario is selected
+ * and provide file manifests for visualization.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/storyboard/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/storyboard/types.ts"],"names":[],"mappings":";AAAA;;;;;;GAMG"}

package/dist/telemetry/coverage.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Telemetry Coverage Analysis
+ *
+ * Measures observability coverage by analyzing which implementation files
+ * contain the OpenTelemetry events documented in canvas nodes.
+ *
+ * Uses codebase-composition's ImplementationFileLayerModule for accurate,
+ * framework-aware detection of implementation files.
+ */
+import type { FileTree } from '@principal-ai/repository-abstraction';
+/**
+ * Per-file instrumentation details
+ */
+export interface FileInstrumentation {
+    filePath: string;
+    expectedEvents: string[];
+    foundEvents: string[];
+    instrumentationCount: number;
+    hasInstrumentation: boolean;
+    missingEvents: string[];
+    isImplementationFile: boolean;
+}
+/**
+ * Node status breakdown
+ */
+export interface NodeStatusBreakdown {
+    missingStatusCount: number;
+    draftCount: number;
+    approvedCount: number;
+    approvedWithFilesCount: number;
+    implementedCount: number;
+    implementedWithFilesCount: number;
+}
+/**
+ * Validation error for a canvas node
+ */
+export interface ValidationError {
+    nodeId: string;
+    canvasPath: string;
+    error: string;
+    status?: string;
+}
+/**
+ * Overall coverage metrics (file-based)
+ */
+export interface CoverageMetrics {
+    totalImplementationFiles: number;
+    filesWithInstrumentation: number;
+    coveragePercentage: number;
+    fileCoverage: FileInstrumentation[];
+    canvasFiles: string[];
+    totalExpectedEvents: number;
+    totalFoundEvents: number;
+    packageCoverage: PackageCoverageMetrics[];
+    nodeStatus: NodeStatusBreakdown;
+    validationErrors: ValidationError[];
+}
+/**
+ * Per-package coverage metrics
+ */
+export interface PackageCoverageMetrics {
+    packageName: string;
+    packagePath: string;
+    totalFiles: number;
+    filesWithInstrumentation: number;
+    coveragePercentage: number;
+    filesByExtension: Record<string, number>;
+}
+/**
+ * Generate telemetry coverage report from canvas files
+ *
+ * Uses codebase-composition's ImplementationFileLayerModule for accurate,
+ * framework-aware detection of implementation files.
+ *
+ * @param fileTree - FileTree representation of the codebase
+ * @param fileReader - Function to read file contents
+ * @returns Coverage metrics based on file instrumentation
+ *
+ * @example
+ * ```typescript
+ * import { FilesystemService, NodeFileSystemAdapter } from '@principal-ai/codebase-composition/node';
+ * import { readFile } from 'fs/promises';
+ * import { resolve } from 'path';
+ *
+ * const service = new FilesystemService(new NodeFileSystemAdapter());
+ * const fileTree = await service.buildFileSystemTreeFromPath('/path/to/project');
+ * const fileReader = async (path: string) => readFile(resolve('/path/to/project', path), 'utf-8');
+ * const metrics = await analyzeCoverage(fileTree, fileReader);
+ * ```
+ */
+export declare function analyzeCoverage(fileTree: FileTree, fileReader: (path: string) => Promise<string>): Promise<CoverageMetrics>;
+//# sourceMappingURL=coverage.d.ts.map

package/dist/telemetry/coverage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"coverage.d.ts","sourceRoot":"","sources":["../../src/telemetry/coverage.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,sCAAsC,CAAC;AAYrE;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,oBAAoB,EAAE,MAAM,CAAC;IAC7B,kBAAkB,EAAE,OAAO,CAAC;IAC5B,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,oBAAoB,EAAE,OAAO,CAAC;CAC/B;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,kBAAkB,EAAE,MAAM,CAAC;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;IACtB,sBAAsB,EAAE,MAAM,CAAC;IAC/B,gBAAgB,EAAE,MAAM,CAAC;IACzB,yBAAyB,EAAE,MAAM,CAAC;CACnC;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAE9B,wBAAwB,EAAE,MAAM,CAAC;IACjC,wBAAwB,EAAE,MAAM,CAAC;IACjC,kBAAkB,EAAE,MAAM,CAAC;IAG3B,YAAY,EAAE,mBAAmB,EAAE,CAAC;IAGpC,WAAW,EAAE,MAAM,EAAE,CAAC;IAGtB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,gBAAgB,EAAE,MAAM,CAAC;IAGzB,eAAe,EAAE,sBAAsB,EAAE,CAAC;IAG1C,UAAU,EAAE,mBAAmB,CAAC;IAGhC,gBAAgB,EAAE,eAAe,EAAE,CAAC;CACrC;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,wBAAwB,EAAE,MAAM,CAAC;IACjC,kBAAkB,EAAE,MAAM,CAAC;IAC3B,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC1C;AAkRD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,eAAe,CACnC,QAAQ,EAAE,QAAQ,EAClB,UAAU,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,GAC5C,OAAO,CAAC,eAAe,CAAC,CAoF1B"}