@industry-theme/principal-view-panels 0.11.36 → 0.11.38

package/dist/components/TraceExpansion.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"TraceExpansion.d.ts","sourceRoot":"","sources":["../../src/components/TraceExpansion.tsx"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAkB,MAAM,OAAO,CAAC;AACvC,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,+BAA+B,CAAC;AAC3D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAErD,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,eAAe,CAAC;IACvB,KAAK,EAAE,KAAK,CAAC;IACb,eAAe,CAAC,EAAE,CAAC,YAAY,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;IACzG,WAAW,CAAC,EAAE,MAAM,IAAI,CAAC;CAC1B;AAsBD,eAAO,MAAM,cAAc,EAAE,KAAK,CAAC,EAAE,CAAC,mBAAmB,CAwPxD,CAAC"}
+{"version":3,"file":"TraceExpansion.d.ts","sourceRoot":"","sources":["../../src/components/TraceExpansion.tsx"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAkB,MAAM,OAAO,CAAC;AACvC,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,+BAA+B,CAAC;AAC3D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAErD,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,eAAe,CAAC;IACvB,KAAK,EAAE,KAAK,CAAC;IACb,eAAe,CAAC,EAAE,CAAC,YAAY,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;IACzG,WAAW,CAAC,EAAE,MAAM,IAAI,CAAC;CAC1B;AAsBD,eAAO,MAAM,cAAc,EAAE,KAAK,CAAC,EAAE,CAAC,mBAAmB,CAgRxD,CAAC"}

package/dist/panels/composable-explanation/ComposableExplanationPanel.d.ts

@@ -0,0 +1,56 @@
+import React from 'react';
+import type { ExtendedCanvas } from '@principal-ai/principal-view-core';
+import type { ComposableExplanation, ExplanationStep } from './types';
+import type { PanelComponentProps, PanelActions, DataSlice } from '../../types';
+import type { FileTree } from '@principal-ai/repository-abstraction';
+/**
+ * Render mode for the canvas
+ */
+export type CanvasRenderMode = 'full' | 'story';
+/**
+ * Typed context for ComposableExplanationPanel
+ */
+export interface ComposableExplanationPanelContext {
+    fileTree: DataSlice<FileTree | null>;
+}
+/**
+ * Typed actions for ComposableExplanationPanel
+ */
+export interface ComposableExplanationPanelActions extends PanelActions {
+    readFile: (path: string) => Promise<string>;
+}
+/**
+ * Props for ComposableExplanationPanel
+ */
+export interface ComposableExplanationPanelProps extends PanelComponentProps<ComposableExplanationPanelActions, ComposableExplanationPanelContext> {
+    /** The explanation document to display */
+    explanation?: ComposableExplanation | null;
+    /** Pre-loaded canvases by alias (for Storybook or when canvases are already available) */
+    canvases?: Map<string, ExtendedCanvas>;
+    /** Legacy: Pre-loaded single canvas */
+    canvas?: ExtendedCanvas | null;
+    /** Initial step index */
+    initialStepIndex?: number;
+    /** Callback when step changes */
+    onStepChange?: (stepIndex: number, step: ExplanationStep) => void;
+    /** Callback when a node is clicked */
+    onNodeClick?: (nodeId: string, event: React.MouseEvent) => void;
+    /** Height of the step carousel */
+    carouselHeight?: number;
+    /** Render mode: 'full' shows entire canvas with highlights, 'story' shows only relevant fragments */
+    renderMode?: CanvasRenderMode;
+    /** Whether to animate transitions in story mode */
+    animateTransitions?: boolean;
+}
+/**
+ * ComposableExplanationPanel
+ *
+ * A panel for displaying agent-generated codebase explanations
+ * with a canvas viewer on top and step-through navigation below.
+ *
+ * Supports two render modes:
+ * - 'full': Shows the entire canvas with highlighted nodes (traditional)
+ * - 'story': Shows only the relevant canvas fragments for each step (focused)
+ */
+export declare const ComposableExplanationPanel: React.FC<ComposableExplanationPanelProps>;
+//# sourceMappingURL=ComposableExplanationPanel.d.ts.map

package/dist/panels/composable-explanation/ComposableExplanationPanel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ComposableExplanationPanel.d.ts","sourceRoot":"","sources":["../../../src/panels/composable-explanation/ComposableExplanationPanel.tsx"],"names":[],"mappings":"AAAA,OAAO,KAA4D,MAAM,OAAO,CAAC;AAGjF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mCAAmC,CAAC;AAIxE,OAAO,KAAK,EACV,qBAAqB,EACrB,eAAe,EAGhB,MAAM,SAAS,CAAC;AACjB,OAAO,KAAK,EAAE,mBAAmB,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAChF,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,sCAAsC,CAAC;AAErE;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,OAAO,CAAC;AA0FhD;;GAEG;AACH,MAAM,WAAW,iCAAiC;IAChD,QAAQ,EAAE,SAAS,CAAC,QAAQ,GAAG,IAAI,CAAC,CAAC;CACtC;AAED;;GAEG;AACH,MAAM,WAAW,iCAAkC,SAAQ,YAAY;IACrE,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;CAC7C;AAED;;GAEG;AACH,MAAM,WAAW,+BACf,SAAQ,mBAAmB,CACzB,iCAAiC,EACjC,iCAAiC,CAClC;IACD,0CAA0C;IAC1C,WAAW,CAAC,EAAE,qBAAqB,GAAG,IAAI,CAAC;IAE3C,0FAA0F;IAC1F,QAAQ,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IAEvC,uCAAuC;IACvC,MAAM,CAAC,EAAE,cAAc,GAAG,IAAI,CAAC;IAE/B,yBAAyB;IACzB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAE1B,iCAAiC;IACjC,YAAY,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,eAAe,KAAK,IAAI,CAAC;IAElE,sCAAsC;IACtC,WAAW,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,CAAC,UAAU,KAAK,IAAI,CAAC;IAEhE,kCAAkC;IAClC,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB,qGAAqG;IACrG,UAAU,CAAC,EAAE,gBAAgB,CAAC;IAE9B,mDAAmD;IACnD,kBAAkB,CAAC,EAAE,OAAO,CAAC;CAC9B;AAWD;;;;;;;;;GASG;AACH,eAAO,MAAM,0BAA0B,EAAE,KAAK,CAAC,EAAE,CAAC,+BAA+B,CAoehF,CAAC"}

package/dist/panels/composable-explanation/StepCarousel.d.ts

@@ -0,0 +1,23 @@
+import React from 'react';
+import type { ExplanationStep } from './types';
+export interface StepCarouselProps {
+    /** Array of explanation steps */
+    steps: ExplanationStep[];
+    /** Currently active step index */
+    currentIndex: number;
+    /** Callback when step changes */
+    onStepChange: (index: number) => void;
+    /** Optional height override */
+    height?: number | string;
+}
+/**
+ * StepCarousel - Bottom navigation component for composable explanations
+ *
+ * Features:
+ * - Left/right arrow navigation
+ * - Step indicator dots
+ * - Current step content display
+ * - Smooth transitions between steps
+ */
+export declare const StepCarousel: React.FC<StepCarouselProps>;
+//# sourceMappingURL=StepCarousel.d.ts.map

package/dist/panels/composable-explanation/StepCarousel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"StepCarousel.d.ts","sourceRoot":"","sources":["../../../src/panels/composable-explanation/StepCarousel.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAsB,MAAM,OAAO,CAAC;AAG3C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAE/C,MAAM,WAAW,iBAAiB;IAChC,iCAAiC;IACjC,KAAK,EAAE,eAAe,EAAE,CAAC;IACzB,kCAAkC;IAClC,YAAY,EAAE,MAAM,CAAC;IACrB,iCAAiC;IACjC,YAAY,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACtC,+BAA+B;IAC/B,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;CAC1B;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,YAAY,EAAE,KAAK,CAAC,EAAE,CAAC,iBAAiB,CAyOpD,CAAC"}

package/dist/panels/composable-explanation/StoryGraphRenderer.d.ts

@@ -0,0 +1,62 @@
+/**
+ * StoryGraphRenderer
+ *
+ * A composite graph renderer that can display fragments from multiple canvases
+ * in a single view, with support for animated transitions between steps.
+ */
+import React from 'react';
+import type { ExtendedCanvas } from '@principal-ai/principal-view-core';
+import { type BridgeEdge, type CompositionConfig } from './canvasFragments';
+/**
+ * A single step's canvas configuration
+ */
+export interface StoryStep {
+    /** Unique step ID */
+    id: string;
+    /** Nodes to show, grouped by canvas alias */
+    nodes: Record<string, string[]>;
+    /** Bridge edges for this step */
+    bridges?: BridgeEdge[];
+    /** Optional highlight node (primary focus) */
+    highlightNodeId?: string;
+    /** Optional layout override for this step */
+    layout?: Partial<CompositionConfig>;
+}
+export interface StoryGraphRendererProps {
+    /** Map of canvas alias to loaded canvas data */
+    canvases: Map<string, ExtendedCanvas>;
+    /** The steps defining what to show */
+    steps: StoryStep[];
+    /** Current step index */
+    currentStepIndex: number;
+    /** Callback when a node is clicked */
+    onNodeClick?: (nodeId: string, sourceAlias: string, originalId: string, event: React.MouseEvent) => void;
+    /** Whether to animate transitions */
+    animateTransitions?: boolean;
+    /** Animation duration in ms */
+    animationDuration?: number;
+    /** Whether to fit view to nodes on step change */
+    fitViewOnStepChange?: boolean;
+    /** Show minimap */
+    showMinimap?: boolean;
+    /** Show controls */
+    showControls?: boolean;
+}
+/**
+ * StoryGraphRenderer - Composite canvas renderer for story-driven explanations
+ */
+export declare const StoryGraphRenderer: React.FC<StoryGraphRendererProps>;
+/**
+ * Helper to convert explanation steps to story steps
+ */
+export declare function explanationStepsToStorySteps(steps: Array<{
+    id: string;
+    ref?: string;
+    refs?: string[];
+    focus?: {
+        existing?: string[];
+        modified?: string[];
+        added?: string[];
+    };
+}>, defaultCanvasAlias?: string): StoryStep[];
+//# sourceMappingURL=StoryGraphRenderer.d.ts.map

package/dist/panels/composable-explanation/StoryGraphRenderer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"StoryGraphRenderer.d.ts","sourceRoot":"","sources":["../../../src/panels/composable-explanation/StoryGraphRenderer.tsx"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAA4D,MAAM,OAAO,CAAC;AAEjF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mCAAmC,CAAC;AAGxE,OAAO,EAKL,KAAK,UAAU,EACf,KAAK,iBAAiB,EACvB,MAAM,mBAAmB,CAAC;AAE3B;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,qBAAqB;IACrB,EAAE,EAAE,MAAM,CAAC;IACX,6CAA6C;IAC7C,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IAChC,iCAAiC;IACjC,OAAO,CAAC,EAAE,UAAU,EAAE,CAAC;IACvB,8CAA8C;IAC9C,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,6CAA6C;IAC7C,MAAM,CAAC,EAAE,OAAO,CAAC,iBAAiB,CAAC,CAAC;CACrC;AAED,MAAM,WAAW,uBAAuB;IACtC,gDAAgD;IAChD,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IACtC,sCAAsC;IACtC,KAAK,EAAE,SAAS,EAAE,CAAC;IACnB,yBAAyB;IACzB,gBAAgB,EAAE,MAAM,CAAC;IACzB,sCAAsC;IACtC,WAAW,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,CAAC,UAAU,KAAK,IAAI,CAAC;IACzG,qCAAqC;IACrC,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,+BAA+B;IAC/B,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,kDAAkD;IAClD,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B,mBAAmB;IACnB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,oBAAoB;IACpB,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED;;GAEG;AACH,eAAO,MAAM,kBAAkB,EAAE,KAAK,CAAC,EAAE,CAAC,uBAAuB,CAsNhE,CAAC;AAEF;;GAEG;AACH,wBAAgB,4BAA4B,CAC1C,KAAK,EAAE,KAAK,CAAC;IACX,EAAE,EAAE,MAAM,CAAC;IACX,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,KAAK,CAAC,EAAE;QACN,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;QACpB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;QACpB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;KAClB,CAAC;CACH,CAAC,EACF,kBAAkB,GAAE,MAAe,GAClC,SAAS,EAAE,CAsDb"}

package/dist/panels/composable-explanation/canvasFragments.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Canvas Fragment Utilities
+ *
+ * Functions for extracting, composing, and laying out canvas fragments
+ * from multiple source canvases into a single composite view.
+ */
+import type { ExtendedCanvas, ExtendedCanvasNode, ExtendedCanvasEdge } from '@principal-ai/principal-view-core';
+/**
+ * A fragment extracted from a canvas
+ */
+export interface CanvasFragment {
+    /** Source canvas alias */
+    sourceAlias: string;
+    /** Extracted nodes */
+    nodes: ExtendedCanvasNode[];
+    /** Extracted edges (only those connecting extracted nodes) */
+    edges: ExtendedCanvasEdge[];
+    /** Bounding box of the fragment */
+    bounds: {
+        minX: number;
+        minY: number;
+        maxX: number;
+        maxY: number;
+        width: number;
+        height: number;
+    };
+}
+/**
+ * A bridge edge connecting nodes from different canvases
+ */
+export interface BridgeEdge {
+    id: string;
+    fromCanvas: string;
+    fromNode: string;
+    toCanvas: string;
+    toNode: string;
+    label?: string;
+    style?: 'solid' | 'dashed' | 'dotted';
+}
+/**
+ * Configuration for composing fragments
+ */
+export interface CompositionConfig {
+    /** How to arrange multiple fragments */
+    layout: 'horizontal' | 'vertical' | 'preserve' | 'auto';
+    /** Gap between fragments when laid out */
+    fragmentGap: number;
+    /** Padding around the entire composition */
+    padding: number;
+    /** Whether to center the composition */
+    center: boolean;
+}
+/**
+ * Result of composing multiple fragments
+ */
+export interface ComposedCanvas {
+    /** The composed canvas data */
+    canvas: ExtendedCanvas;
+    /** Map of original node IDs to composed node IDs */
+    nodeIdMap: Map<string, string>;
+    /** Source fragment info for each node */
+    nodeSourceMap: Map<string, {
+        alias: string;
+        originalId: string;
+    }>;
+}
+/**
+ * Default composition config
+ */
+export declare const DEFAULT_COMPOSITION_CONFIG: CompositionConfig;
+/**
+ * Extract a fragment from a canvas containing only specified nodes
+ * and edges connecting those nodes.
+ */
+export declare function extractFragment(canvas: ExtendedCanvas, nodeIds: string[], sourceAlias: string): CanvasFragment;
+/**
+ * Calculate the bounding box of a set of nodes
+ */
+export declare function calculateBounds(nodes: ExtendedCanvasNode[]): CanvasFragment['bounds'];
+/**
+ * Compose multiple canvas fragments into a single canvas
+ */
+export declare function composeFragments(fragments: CanvasFragment[], bridgeEdges?: BridgeEdge[], config?: Partial<CompositionConfig>): ComposedCanvas;
+/**
+ * Create a step-specific composed view from an explanation step
+ */
+export interface StepCanvasConfig {
+    /** Node IDs to include, grouped by canvas alias */
+    nodes: Record<string, string[]>;
+    /** Bridge edges between canvases */
+    bridges?: BridgeEdge[];
+    /** Layout configuration */
+    layout?: Partial<CompositionConfig>;
+}
+/**
+ * Build a composed canvas for a specific step
+ */
+export declare function buildStepCanvas(canvases: Map<string, ExtendedCanvas>, config: StepCanvasConfig): ComposedCanvas | null;
+/**
+ * Calculate which nodes changed between two steps
+ * Useful for animating transitions
+ */
+export interface StepTransition {
+    /** Nodes that are new in the next step */
+    entering: string[];
+    /** Nodes that are removed in the next step */
+    exiting: string[];
+    /** Nodes that remain (may change position) */
+    staying: string[];
+}
+export declare function calculateStepTransition(currentNodes: Set<string>, nextNodes: Set<string>): StepTransition;
+//# sourceMappingURL=canvasFragments.d.ts.map

package/dist/panels/composable-explanation/canvasFragments.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"canvasFragments.d.ts","sourceRoot":"","sources":["../../../src/panels/composable-explanation/canvasFragments.ts"],"names":[],"mappings":"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"}

package/dist/panels/composable-explanation/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Composable Explanation Panel
+ *
+ * A panel for displaying agent-generated codebase explanations
+ * with a canvas viewer on top and step-through navigation below.
+ *
+ * Supports two render modes:
+ * - 'full': Shows the entire canvas with highlighted nodes
+ * - 'story': Shows only the relevant canvas fragments for each step (focused view)
+ */
+export { ComposableExplanationPanel } from './ComposableExplanationPanel';
+export type { ComposableExplanationPanelProps, ComposableExplanationPanelContext, ComposableExplanationPanelActions, CanvasRenderMode, } from './ComposableExplanationPanel';
+export { StepCarousel } from './StepCarousel';
+export type { StepCarouselProps } from './StepCarousel';
+export { StoryGraphRenderer, explanationStepsToStorySteps } from './StoryGraphRenderer';
+export type { StoryGraphRendererProps, StoryStep } from './StoryGraphRenderer';
+export { extractFragment, composeFragments, buildStepCanvas, calculateBounds, calculateStepTransition, DEFAULT_COMPOSITION_CONFIG, } from './canvasFragments';
+export type { CanvasFragment, BridgeEdge, CompositionConfig, ComposedCanvas, StepCanvasConfig, StepTransition, } from './canvasFragments';
+export type { ComposableExplanation, ExplanationStep, ExplanationType, CanvasRegistry, EntityMapping, CanvasBridge, ViewFocus, FocusType, ProposedElement, LoadedCanvas, ExplanationViewerState, ElementRef, } from './types';
+//# sourceMappingURL=index.d.ts.map

package/dist/panels/composable-explanation/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/panels/composable-explanation/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,0BAA0B,EAAE,MAAM,8BAA8B,CAAC;AAC1E,YAAY,EACV,+BAA+B,EAC/B,iCAAiC,EACjC,iCAAiC,EACjC,gBAAgB,GACjB,MAAM,8BAA8B,CAAC;AAEtC,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,YAAY,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAExD,OAAO,EAAE,kBAAkB,EAAE,4BAA4B,EAAE,MAAM,sBAAsB,CAAC;AACxF,YAAY,EAAE,uBAAuB,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAE/E,OAAO,EACL,eAAe,EACf,gBAAgB,EAChB,eAAe,EACf,eAAe,EACf,uBAAuB,EACvB,0BAA0B,GAC3B,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EACV,cAAc,EACd,UAAU,EACV,iBAAiB,EACjB,cAAc,EACd,gBAAgB,EAChB,cAAc,GACf,MAAM,mBAAmB,CAAC;AAE3B,YAAY,EACV,qBAAqB,EACrB,eAAe,EACf,eAAe,EACf,cAAc,EACd,aAAa,EACb,YAAY,EACZ,SAAS,EACT,SAAS,EACT,eAAe,EACf,YAAY,EACZ,sBAAsB,EACtB,UAAU,GACX,MAAM,SAAS,CAAC"}

package/dist/panels/composable-explanation/types.d.ts

@@ -0,0 +1,147 @@
+/**
+ * Types for Composable Explanation Documents
+ *
+ * These types define the format for agent-generated codebase explanations
+ * that compose existing canvas visualizations with narrative content.
+ */
+import type { ExtendedCanvas } from '@principal-ai/principal-view-core';
+/**
+ * Reference to a canvas element using canvas-alias:element-id format
+ */
+export type ElementRef = string;
+/**
+ * Focus annotation types for visual treatment
+ */
+export type FocusType = 'existing' | 'modified' | 'added' | 'removed' | 'error' | 'current';
+/**
+ * Proposed element that doesn't exist in the canvas yet
+ */
+export interface ProposedElement {
+    id: string;
+    after?: string;
+    label: string;
+    description?: string;
+}
+/**
+ * Focus configuration for a view
+ */
+export interface ViewFocus {
+    /** Relevant existing elements - standard highlight */
+    existing?: string[];
+    /** Changed elements - yellow/amber */
+    modified?: string[];
+    /** New elements (proposed or actual) - green */
+    added?: string[];
+    /** Deleted elements - red/strikethrough */
+    removed?: string[];
+    /** Proposed elements that don't exist yet */
+    proposed?: ProposedElement[];
+}
+/**
+ * A single step in the explanation walkthrough
+ */
+export interface ExplanationStep {
+    /** Unique ID for this step */
+    id: string;
+    /** Element reference to highlight (canvas-alias:element-id) */
+    ref?: ElementRef;
+    /** Array of element refs if highlighting multiple */
+    refs?: ElementRef[];
+    /** Narrative content for this step (markdown supported) */
+    content: string;
+    /** Optional source file reference */
+    source?: string;
+    /** Focus configuration for canvas highlighting */
+    focus?: ViewFocus;
+    /** Optional title for the step */
+    title?: string;
+}
+/**
+ * Canvas registry mapping aliases to file paths
+ */
+export interface CanvasRegistry {
+    [alias: string]: string;
+}
+/**
+ * Entity mapping showing same logical entity across canvases
+ */
+export interface EntityMapping {
+    [entityId: string]: {
+        description: string;
+        occurrences: ElementRef[];
+    };
+}
+/**
+ * Cross-canvas bridge connection
+ */
+export interface CanvasBridge {
+    id: string;
+    from: ElementRef;
+    to: ElementRef;
+    label?: string;
+    type?: 'sync' | 'async' | 'event';
+}
+/**
+ * Explanation document types
+ */
+export type ExplanationType = 'code-review' | 'design-spec' | 'exploration' | 'incident-analysis' | 'onboarding' | 'impact-analysis';
+/**
+ * Main explanation document structure
+ */
+export interface ComposableExplanation {
+    /** Document type */
+    type: ExplanationType;
+    /** Semantic version */
+    version: string;
+    /** Document title */
+    title: string;
+    /** Optional summary/description */
+    summary?: string;
+    /** Question being answered (for exploration type) */
+    question?: string;
+    /** Canvas registry - aliases to file paths */
+    canvases: CanvasRegistry;
+    /** Entity mappings across canvases */
+    entities?: EntityMapping;
+    /** Cross-canvas bridges */
+    bridges?: CanvasBridge[];
+    /** Scope of the explanation */
+    scope?: {
+        files?: string[];
+        areas?: string[];
+    };
+    /** The walkthrough steps */
+    steps: ExplanationStep[];
+    /** Related resources */
+    related?: {
+        scenarios?: string[];
+        sources?: string[];
+        workflows?: string[];
+    };
+}
+/**
+ * Loaded canvas data with alias
+ */
+export interface LoadedCanvas {
+    alias: string;
+    path: string;
+    canvas: ExtendedCanvas;
+}
+/**
+ * Runtime state for the explanation viewer
+ */
+export interface ExplanationViewerState {
+    /** Currently active step index */
+    currentStepIndex: number;
+    /** Loaded canvases by alias */
+    loadedCanvases: Map<string, LoadedCanvas>;
+    /** Currently highlighted node IDs */
+    highlightedNodeIds: string[];
+    /** Active node IDs (all nodes in current step's focus) */
+    activeNodeIds: string[];
+    /** Loading state */
+    loading: boolean;
+    /** Error message if any */
+    error: string | null;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/panels/composable-explanation/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/panels/composable-explanation/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAoB,MAAM,mCAAmC,CAAC;AAE1F;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC;AAEhC;;GAEG;AACH,MAAM,MAAM,SAAS,GAAG,UAAU,GAAG,UAAU,GAAG,OAAO,GAAG,SAAS,GAAG,OAAO,GAAG,SAAS,CAAC;AAE5F;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,sDAAsD;IACtD,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,sCAAsC;IACtC,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,gDAAgD;IAChD,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,2CAA2C;IAC3C,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,6CAA6C;IAC7C,QAAQ,CAAC,EAAE,eAAe,EAAE,CAAC;CAC9B;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,8BAA8B;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,+DAA+D;IAC/D,GAAG,CAAC,EAAE,UAAU,CAAC;IACjB,qDAAqD;IACrD,IAAI,CAAC,EAAE,UAAU,EAAE,CAAC;IACpB,2DAA2D;IAC3D,OAAO,EAAE,MAAM,CAAC;IAChB,qCAAqC;IACrC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,kDAAkD;IAClD,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB,kCAAkC;IAClC,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,CAAC,QAAQ,EAAE,MAAM,GAAG;QAClB,WAAW,EAAE,MAAM,CAAC;QACpB,WAAW,EAAE,UAAU,EAAE,CAAC;KAC3B,CAAC;CACH;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,UAAU,CAAC;IACjB,EAAE,EAAE,UAAU,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,GAAG,OAAO,CAAC;CACnC;AAED;;GAEG;AACH,MAAM,MAAM,eAAe,GACvB,aAAa,GACb,aAAa,GACb,aAAa,GACb,mBAAmB,GACnB,YAAY,GACZ,iBAAiB,CAAC;AAEtB;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,oBAAoB;IACpB,IAAI,EAAE,eAAe,CAAC;IACtB,uBAAuB;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,qBAAqB;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,mCAAmC;IACnC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,qDAAqD;IACrD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB,8CAA8C;IAC9C,QAAQ,EAAE,cAAc,CAAC;IAEzB,sCAAsC;IACtC,QAAQ,CAAC,EAAE,aAAa,CAAC;IAEzB,2BAA2B;IAC3B,OAAO,CAAC,EAAE,YAAY,EAAE,CAAC;IAEzB,+BAA+B;IAC/B,KAAK,CAAC,EAAE;QACN,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;QACjB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;KAClB,CAAC;IAEF,4BAA4B;IAC5B,KAAK,EAAE,eAAe,EAAE,CAAC;IAEzB,wBAAwB;IACxB,OAAO,CAAC,EAAE;QACR,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;QACrB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;QACnB,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;KACtB,CAAC;CACH;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,cAAc,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,kCAAkC;IAClC,gBAAgB,EAAE,MAAM,CAAC;IACzB,+BAA+B;IAC/B,cAAc,EAAE,GAAG,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;IAC1C,qCAAqC;IACrC,kBAAkB,EAAE,MAAM,EAAE,CAAC;IAC7B,0DAA0D;IAC1D,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,oBAAoB;IACpB,OAAO,EAAE,OAAO,CAAC;IACjB,2BAA2B;IAC3B,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB"}

package/dist/panels.bundle.js

@@ -100291,6 +100291,19 @@ const TraceExpansion = ({
   onWorkflowClick,
   onSpanClick
 }) => {
+  const spanIndexMap = useMemo(() => {
+    var _a;
+    const map2 = /* @__PURE__ */ new Map();
+    let index2 = 0;
+    for (const resourceSpan of ((_a = trace.otlpData) == null ? void 0 : _a.resourceSpans) || []) {
+      for (const scopeSpan of resourceSpan.scopeSpans || []) {
+        for (const span of scopeSpan.spans || []) {
+          map2.set(span.spanId, index2++);
+        }
+      }
+    }
+    return map2;
+  }, [trace.otlpData]);
   const sortedSpans = useMemo(() => {
     var _a, _b, _c, _d;
     const spans = [];
@@ -100349,8 +100362,14 @@ const TraceExpansion = ({
       ...span,
       depth: getDepth(span.spanId)
     }));
-    return spansWithDepth.sort((a, b) => a.timestamp - b.timestamp);
-  }, [trace.scenarioMatches, trace.storyboardMatches, trace.unmatchedSpans]);
+    return spansWithDepth.sort((a, b) => {
+      const timeDiff = a.timestamp - b.timestamp;
+      if (timeDiff !== 0) return timeDiff;
+      const indexA = spanIndexMap.get(a.spanId) ?? Infinity;
+      const indexB = spanIndexMap.get(b.spanId) ?? Infinity;
+      return indexA - indexB;
+    });
+  }, [trace.scenarioMatches, trace.storyboardMatches, trace.unmatchedSpans, spanIndexMap]);
   const hasAnyMatches = sortedSpans.length > 0;
   return /* @__PURE__ */ jsxs(
     "div",
@@ -100425,7 +100444,7 @@ const TraceExpansion = ({
                   {
                     style: {
                       fontSize: theme2.fontSizes[1],
-                      color: span.reason.includes("No storyboards found for scope") ? theme2.colors.error || "#ef4444" : theme2.colors.textMuted,
+                      color: span.reason.includes("not registered in any owned-scopes") || span.reason.includes("has no storyboards") ? theme2.colors.error || "#ef4444" : theme2.colors.textMuted,
                       marginLeft: theme2.space[2],
                       fontStyle: "italic"
                     },
@@ -100683,7 +100702,7 @@ const TraceList = ({
                     display: "flex",
                     alignItems: "center",
                     gap: theme2.space[1],
-                    padding: `${theme2.space[1]} ${theme2.space[2]}`,
+                    padding: `${theme2.space[1]}px ${theme2.space[2]}px`,
                     fontSize: theme2.fontSizes[1],
                     fontFamily: theme2.fonts.body,
                     color: theme2.colors.error,