@principal-ai/subsystems-react 0.17.0

package/src/components/session-events/index.ts

@@ -0,0 +1,13 @@
+/**
+ * Session event diagnostic feed — raw → repo-normalized → accumulated pipeline
+ * per event, rendered as a three-column feed.
+ */
+export {
+  SessionEventFeed,
+  SessionEventFeedGrouped,
+} from './SessionEventFeed';
+export type {
+  SessionEventFeedProps,
+  SessionEventFeedGroupedProps,
+  SessionEventFeedRow,
+} from './SessionEventFeed';

package/src/components/state-view/PipelineView.tsx

@@ -0,0 +1,347 @@
+/**
+ * PipelineView Component
+ *
+ * A state-driven visualization showing data flowing through pipeline stages.
+ * Demonstrates the state view pattern with animations.
+ */
+
+import React from 'react';
+import type {
+  PipelineState,
+  PipelineEvent,
+  PipelineStage,
+  EventSource,
+  TransitionDefinition,
+} from './types';
+import { useStateView } from './useStateView';
+
+// =============================================================================
+// Reducer
+// =============================================================================
+
+const initialPipelineState: PipelineState = {
+  stages: {
+    disk: { id: 'disk', label: 'Disk', lastEventTime: null, isActive: false },
+    watch: { id: 'watch', label: 'Watch', lastEventTime: null, isActive: false },
+    cache: { id: 'cache', label: 'Cache', lastEventTime: null, isActive: false, count: 0 },
+    event: { id: 'event', label: 'Events', lastEventTime: null, isActive: false, count: 0 },
+  },
+  repos: new Map(),
+  totalEvents: 0,
+};
+
+function pipelineReducer(state: PipelineState, event: PipelineEvent): PipelineState {
+  const now = event.timestamp;
+
+  switch (event.type) {
+    case 'FS_CHANGE':
+      return {
+        ...state,
+        stages: {
+          ...state.stages,
+          disk: { ...state.stages.disk, lastEventTime: now, isActive: true },
+        },
+        totalEvents: state.totalEvents + 1,
+      };
+
+    case 'WATCH_DETECTED':
+      return {
+        ...state,
+        stages: {
+          ...state.stages,
+          watch: { ...state.stages.watch, lastEventTime: now, isActive: true },
+        },
+      };
+
+    case 'CACHE_REBUILD':
+    case 'CACHE_HIT': {
+      const newRepos = new Map(state.repos);
+      if (event.payload.repo) {
+        newRepos.set(event.payload.repo, {
+          path: event.payload.repo,
+          lastEventTime: now,
+          lastEventType: event.type,
+        });
+      }
+      return {
+        ...state,
+        stages: {
+          ...state.stages,
+          cache: {
+            ...state.stages.cache,
+            lastEventTime: now,
+            isActive: true,
+            count: (state.stages.cache.count ?? 0) + 1,
+          },
+        },
+        repos: newRepos,
+      };
+    }
+
+    case 'EVENT_BROADCAST':
+      return {
+        ...state,
+        stages: {
+          ...state.stages,
+          event: {
+            ...state.stages.event,
+            lastEventTime: now,
+            isActive: true,
+            count: (state.stages.event.count ?? 0) + 1,
+          },
+        },
+      };
+
+    default:
+      return state;
+  }
+}
+
+// =============================================================================
+// Transitions
+// =============================================================================
+
+const pipelineTransitions: TransitionDefinition[] = [
+  { watch: 'stages.disk.lastEventTime', condition: 'changed', animate: 'pulse', target: 'stage-disk' },
+  { watch: 'stages.watch.lastEventTime', condition: 'changed', animate: 'pulse', target: 'stage-watch' },
+  { watch: 'stages.cache.lastEventTime', condition: 'changed', animate: 'pulse', target: 'stage-cache' },
+  { watch: 'stages.event.lastEventTime', condition: 'changed', animate: 'pulse', target: 'stage-event' },
+  { watch: 'stages.event.count', condition: 'increased', animate: 'particle-flow', target: 'flow-cache-event' },
+];
+
+// =============================================================================
+// Sub-Components
+// =============================================================================
+
+interface StageBoxProps {
+  stage: PipelineStage;
+  isAnimating: boolean;
+}
+
+function StageBox({ stage, isAnimating }: StageBoxProps) {
+  const baseStyle: React.CSSProperties = {
+    display: 'flex',
+    flexDirection: 'column',
+    alignItems: 'center',
+    justifyContent: 'center',
+    width: 100,
+    height: 80,
+    borderRadius: 8,
+    backgroundColor: stage.isActive ? '#3b82f6' : '#374151',
+    color: 'white',
+    fontFamily: 'system-ui, sans-serif',
+    transition: 'all 0.3s ease',
+    boxShadow: isAnimating ? '0 0 20px rgba(59, 130, 246, 0.8)' : 'none',
+    transform: isAnimating ? 'scale(1.05)' : 'scale(1)',
+  };
+
+  return (
+    <div id={`stage-${stage.id}`} style={baseStyle}>
+      <div style={{ fontWeight: 'bold', fontSize: 14 }}>{stage.label}</div>
+      {stage.count !== undefined && (
+        <div style={{ fontSize: 20, fontWeight: 'bold' }}>{stage.count}</div>
+      )}
+      {stage.lastEventTime && (
+        <div style={{ fontSize: 10, opacity: 0.7 }}>
+          {formatTimeAgo(stage.lastEventTime)}
+        </div>
+      )}
+    </div>
+  );
+}
+
+interface FlowArrowProps {
+  id: string;
+  isAnimating: boolean;
+}
+
+function FlowArrow({ id, isAnimating }: FlowArrowProps) {
+  const style: React.CSSProperties = {
+    display: 'flex',
+    alignItems: 'center',
+    justifyContent: 'center',
+    width: 60,
+    height: 40,
+    color: isAnimating ? '#3b82f6' : '#6b7280',
+    fontSize: 24,
+    transition: 'color 0.3s ease',
+  };
+
+  return (
+    <div id={id} style={style}>
+      {isAnimating ? (
+        <span style={{ animation: 'pulse 0.5s ease-in-out' }}>→→→</span>
+      ) : (
+        '→'
+      )}
+    </div>
+  );
+}
+
+function formatTimeAgo(timestamp: number): string {
+  const seconds = Math.floor((Date.now() - timestamp) / 1000);
+  if (seconds < 60) return `${seconds}s ago`;
+  const minutes = Math.floor(seconds / 60);
+  if (minutes < 60) return `${minutes}m ago`;
+  const hours = Math.floor(minutes / 60);
+  return `${hours}h ago`;
+}
+
+// =============================================================================
+// Main Component
+// =============================================================================
+
+export interface PipelineViewProps {
+  eventSource: EventSource<PipelineEvent>;
+  title?: string;
+}
+
+export function PipelineView({ eventSource, title = 'Pipeline View' }: PipelineViewProps) {
+  const { state, animations, isReplay, reset } = useStateView<PipelineState, PipelineEvent>({
+    initialState: initialPipelineState,
+    reducer: pipelineReducer,
+    eventSource,
+    transitions: pipelineTransitions,
+  });
+
+  const isStageAnimating = (stageId: string) =>
+    animations.some((a) => a.target === `stage-${stageId}`);
+
+  const isFlowAnimating = (flowId: string) =>
+    animations.some((a) => a.target === flowId);
+
+  const containerStyle: React.CSSProperties = {
+    fontFamily: 'system-ui, sans-serif',
+    backgroundColor: '#1f2937',
+    color: 'white',
+    padding: 24,
+    borderRadius: 12,
+    minWidth: 600,
+  };
+
+  const headerStyle: React.CSSProperties = {
+    display: 'flex',
+    justifyContent: 'space-between',
+    alignItems: 'center',
+    marginBottom: 24,
+  };
+
+  const pipelineStyle: React.CSSProperties = {
+    display: 'flex',
+    alignItems: 'center',
+    justifyContent: 'center',
+    gap: 8,
+    marginBottom: 24,
+  };
+
+  const statsStyle: React.CSSProperties = {
+    display: 'flex',
+    gap: 24,
+    justifyContent: 'center',
+    padding: '16px 0',
+    borderTop: '1px solid #374151',
+  };
+
+  const statBoxStyle: React.CSSProperties = {
+    textAlign: 'center',
+  };
+
+  const repoListStyle: React.CSSProperties = {
+    marginTop: 16,
+    padding: 16,
+    backgroundColor: '#111827',
+    borderRadius: 8,
+    maxHeight: 200,
+    overflowY: 'auto',
+  };
+
+  return (
+    <div style={containerStyle}>
+      <div style={headerStyle}>
+        <h2 style={{ margin: 0 }}>{title}</h2>
+        <div style={{ display: 'flex', gap: 8, alignItems: 'center' }}>
+          {isReplay && (
+            <span style={{ fontSize: 12, color: '#f59e0b' }}>REPLAY</span>
+          )}
+          <button
+            onClick={reset}
+            style={{
+              padding: '4px 12px',
+              borderRadius: 4,
+              border: 'none',
+              backgroundColor: '#374151',
+              color: 'white',
+              cursor: 'pointer',
+            }}
+          >
+            Reset
+          </button>
+        </div>
+      </div>
+
+      {/* Pipeline Stages */}
+      <div style={pipelineStyle}>
+        <StageBox stage={state.stages.disk} isAnimating={isStageAnimating('disk')} />
+        <FlowArrow id="flow-disk-watch" isAnimating={isFlowAnimating('flow-disk-watch')} />
+        <StageBox stage={state.stages.watch} isAnimating={isStageAnimating('watch')} />
+        <FlowArrow id="flow-watch-cache" isAnimating={isFlowAnimating('flow-watch-cache')} />
+        <StageBox stage={state.stages.cache} isAnimating={isStageAnimating('cache')} />
+        <FlowArrow id="flow-cache-event" isAnimating={isFlowAnimating('flow-cache-event')} />
+        <StageBox stage={state.stages.event} isAnimating={isStageAnimating('event')} />
+      </div>
+
+      {/* Stats */}
+      <div style={statsStyle}>
+        <div style={statBoxStyle}>
+          <div style={{ fontSize: 24, fontWeight: 'bold' }}>{state.repos.size}</div>
+          <div style={{ fontSize: 12, color: '#9ca3af' }}>Repos</div>
+        </div>
+        <div style={statBoxStyle}>
+          <div style={{ fontSize: 24, fontWeight: 'bold' }}>{state.stages.cache.count}</div>
+          <div style={{ fontSize: 12, color: '#9ca3af' }}>Cache Ops</div>
+        </div>
+        <div style={statBoxStyle}>
+          <div style={{ fontSize: 24, fontWeight: 'bold' }}>{state.stages.event.count}</div>
+          <div style={{ fontSize: 12, color: '#9ca3af' }}>Events</div>
+        </div>
+        <div style={statBoxStyle}>
+          <div style={{ fontSize: 24, fontWeight: 'bold' }}>{state.totalEvents}</div>
+          <div style={{ fontSize: 12, color: '#9ca3af' }}>Total</div>
+        </div>
+      </div>
+
+      {/* Repo List */}
+      {state.repos.size > 0 && (
+        <div style={repoListStyle}>
+          <div style={{ fontSize: 12, color: '#9ca3af', marginBottom: 8 }}>
+            Active Repositories
+          </div>
+          {Array.from(state.repos.values()).map((repo) => (
+            <div
+              key={repo.path}
+              style={{
+                display: 'flex',
+                justifyContent: 'space-between',
+                padding: '4px 0',
+                borderBottom: '1px solid #374151',
+              }}
+            >
+              <span style={{ fontSize: 13 }}>{repo.path}</span>
+              <span style={{ fontSize: 11, color: '#9ca3af' }}>
+                {repo.lastEventType} - {formatTimeAgo(repo.lastEventTime)}
+              </span>
+            </div>
+          ))}
+        </div>
+      )}
+
+      {/* CSS for animations */}
+      <style>{`
+        @keyframes pulse {
+          0%, 100% { opacity: 1; }
+          50% { opacity: 0.5; }
+        }
+      `}</style>
+    </div>
+  );
+}

package/src/components/state-view/index.ts

@@ -0,0 +1,14 @@
+/**
+ * State View Components
+ *
+ * A pattern for state-driven visualizations where:
+ * - Telemetry events are processed into state changes
+ * - State has a defined shape
+ * - State changes trigger animations/transitions
+ */
+
+export * from './types';
+export { useStateView } from './useStateView';
+export type { UseStateViewOptions, UseStateViewResult } from './useStateView';
+export { PipelineView } from './PipelineView';
+export type { PipelineViewProps } from './PipelineView';

package/src/components/state-view/types.ts

@@ -0,0 +1,261 @@
+/**
+ * State View Types
+ *
+ * A state-based visualization system where:
+ * - Telemetry events are processed into state changes
+ * - State has a defined shape
+ * - State changes trigger animations/transitions
+ */
+
+// =============================================================================
+// Core Event Types
+// =============================================================================
+
+/**
+ * A state event extracted from telemetry (OTEL spans, etc.)
+ */
+export interface StateEvent<TPayload = Record<string, unknown>> {
+  /** Event type identifier */
+  type: string;
+  /** When this event occurred */
+  timestamp: number;
+  /** Event-specific data */
+  payload: TPayload;
+  /** Optional trace correlation */
+  traceId?: string;
+  spanId?: string;
+}
+
+/**
+ * Source of events - can be live (IPC/WebSocket) or replay (from storage)
+ */
+export interface EventSource<TEvent extends StateEvent = StateEvent> {
+  /** Subscribe to events, returns unsubscribe function */
+  subscribe(handler: (event: TEvent) => void): () => void;
+  /** Optional: current mode */
+  mode?: 'live' | 'replay';
+}
+
+// =============================================================================
+// State Types
+// =============================================================================
+
+/**
+ * A reducer that applies events to state
+ */
+export type StateReducer<TState, TEvent extends StateEvent> = (
+  state: TState,
+  event: TEvent
+) => TState;
+
+/**
+ * Describes what changed between two states (for animations)
+ */
+export interface StateDiff<TState> {
+  /** Previous state */
+  prev: TState;
+  /** New state */
+  next: TState;
+  /** Which paths changed (dot notation) */
+  changedPaths: string[];
+  /** The event that caused this change */
+  event: StateEvent;
+}
+
+// =============================================================================
+// Animation/Transition Types
+// =============================================================================
+
+export type AnimationType =
+  | 'pulse'
+  | 'glow'
+  | 'flash'
+  | 'shake'
+  | 'slide-in'
+  | 'slide-out'
+  | 'fade-in'
+  | 'fade-out'
+  | 'particle-flow'
+  | 'increment'
+  | 'decrement'
+  | 'bar-change';
+
+export interface TransitionDefinition {
+  /** Condition: which state path to watch */
+  watch: string;
+  /** Condition type */
+  condition: 'changed' | 'increased' | 'decreased' | 'added' | 'removed';
+  /** Animation to trigger */
+  animate: AnimationType;
+  /** Target element (CSS selector or element ID) */
+  target?: string;
+  /** Duration in ms */
+  duration?: number;
+  /** Additional params */
+  params?: Record<string, unknown>;
+}
+
+export interface ActiveAnimation {
+  id: string;
+  type: AnimationType;
+  target: string;
+  startTime: number;
+  duration: number;
+  params?: Record<string, unknown>;
+}
+
+// =============================================================================
+// Replay Types
+// =============================================================================
+
+export interface ReplayControls {
+  /** Current playback state */
+  state: 'playing' | 'paused' | 'stopped';
+  /** Playback speed multiplier */
+  speed: number;
+  /** Current replay time (event time, not wall time) */
+  currentTime: number;
+  /** Start of replay range */
+  startTime: number;
+  /** End of replay range */
+  endTime: number;
+  /** Control methods */
+  play: () => void;
+  pause: () => void;
+  stop: () => void;
+  seek: (time: number) => void;
+  setSpeed: (speed: number) => void;
+}
+
+// =============================================================================
+// Pipeline View Specific Types (Case Study 1)
+// =============================================================================
+
+export interface PipelineStage {
+  id: string;
+  label: string;
+  lastEventTime: number | null;
+  isActive: boolean;
+  count?: number;
+}
+
+export interface PipelineRepoState {
+  path: string;
+  lastEventTime: number;
+  lastEventType: string;
+}
+
+export interface PipelineState {
+  stages: Record<string, PipelineStage>;
+  repos: Map<string, PipelineRepoState>;
+  totalEvents: number;
+}
+
+export type PipelineEventType =
+  | 'FS_CHANGE'
+  | 'WATCH_DETECTED'
+  | 'CACHE_REBUILD'
+  | 'CACHE_HIT'
+  | 'EVENT_BROADCAST';
+
+export interface PipelineEvent extends StateEvent {
+  type: PipelineEventType;
+  payload: {
+    repo?: string;
+    stage?: string;
+    slice?: string;
+    eventType?: string;
+  };
+}
+
+// =============================================================================
+// Activity View Specific Types (Case Study 2)
+// =============================================================================
+
+export interface RoomState {
+  id: string;
+  userCount: number;
+  users: Set<string>;
+}
+
+export interface ActivityState {
+  rooms: Map<string, RoomState>;
+  totalUsers: number;
+  syncRatePerMinute: number;
+  recentSyncs: number[];
+}
+
+export type ActivityEventType =
+  | 'ROOM_JOIN'
+  | 'ROOM_LEAVE'
+  | 'SYNC_BROADCAST';
+
+export interface ActivityEvent extends StateEvent {
+  type: ActivityEventType;
+  payload: {
+    roomId?: string;
+    userId?: string;
+    userLogin?: string;
+    syncType?: string;
+  };
+}
+
+// =============================================================================
+// Quota View Specific Types (Case Study 3)
+// =============================================================================
+
+export interface UserQuotaState {
+  userId: number;
+  userLogin: string;
+  remaining: number;
+  limit: number;
+  resetTime: number;
+  callsThisHour: number;
+  cacheHits: number;
+  byOperation: Map<string, { total: number; apiCalls: number }>;
+  byRepo: Map<string, { total: number; apiCalls: number }>;
+}
+
+export interface QuotaDistributionState {
+  users: Map<number, UserQuotaState>;
+  serverRemaining: number;
+  serverResetTime: number;
+}
+
+export type QuotaEventType = 'GITHUB_REQUEST';
+
+export interface QuotaEvent extends StateEvent {
+  type: QuotaEventType;
+  payload: {
+    userId?: number;
+    userLogin?: string;
+    tokenType: 'user' | 'server';
+    operation: string;
+    repoOwner?: string;
+    repoName?: string;
+    cacheHit: boolean;
+    cacheTier?: string;
+    ratelimitRemaining?: number;
+    ratelimitLimit?: number;
+    ratelimitReset?: number;
+  };
+}
+
+// =============================================================================
+// View Definition (Schema)
+// =============================================================================
+
+export interface StateViewDefinition<TState, TEvent extends StateEvent> {
+  id: string;
+  name: string;
+  description?: string;
+
+  /** Initial state */
+  initialState: TState;
+
+  /** Reducer function or reference */
+  reducer: StateReducer<TState, TEvent>;
+
+  /** Transition definitions for animations */
+  transitions?: TransitionDefinition[];
+}