@principal-ai/subsystems-react 0.17.0

package/src/subsystem/paths.ts

@@ -0,0 +1,127 @@
+/**
+ * Multi-repo path handling for subsystem graphs.
+ *
+ * A component's `file` is relative to ITS OWN repo root — the repo identified
+ * by its `purl` (`pkg:github/<owner>/<name>[#<path>]`) — never to the machine.
+ * When a graph spans several repos the sidebar tree needs synthetic
+ * `<owner>/<name>/` prefixes to keep same-named paths apart; hosts resolve
+ * each file against `repoRoots[purlRepo] ?? repoRoot`.
+ */
+
+/** Normalize a purl to its repo key: fragment and surrounding whitespace stripped. */
+export function purlRepoKey(purl: string | undefined): string | undefined {
+  if (!purl) return undefined;
+  const base = purl.split('#')[0]?.trim();
+  return base || undefined;
+}
+
+/** `owner/name` from a purl (`pkg:github/acme/widget#x/y.ts` → `acme/widget`). */
+export function purlOwnerName(purl: string | undefined): string | undefined {
+  const key = purlRepoKey(purl);
+  if (!key) return undefined;
+  // pkg:<type>/<owner>/<name> → take the last two segments.
+  const parts = key.split('/').filter(Boolean);
+  if (parts.length < 2) return undefined;
+  return `${parts[parts.length - 2]}/${parts[parts.length - 1]}`;
+}
+
+export interface TreeEntry {
+  /** Path as shown in the sidebar tree (repo-prefixed when multi-repo). */
+  displayPath: string;
+  /** The component's own file value — what hosts resolve + drawers open. */
+  file: string;
+}
+
+export interface TreePathMapping {
+  entries: TreeEntry[];
+  /** True when components span more than one repo (prefixes are shown). */
+  multiRepo: boolean;
+  /** displayPath → file. */
+  toFile: Map<string, string>;
+  /** file → displayPath (first component wins). */
+  toDisplay: Map<string, string>;
+}
+
+/**
+ * Build the sidebar tree's path set from components. Single-repo graphs (and
+ * purl-less components) keep bare `file` values; mixed-repo graphs prefix each
+ * entry with its purl's `owner/name` so the tree groups by repo.
+ */
+export function buildTreePathMapping(components: ReadonlyArray<{ file?: string; purl?: string }>): TreePathMapping {
+  const withFiles = components.filter((c) => c.file);
+  const repos = new Set(
+    withFiles.map((c) => purlRepoKey(c.purl)).filter((k): k is string => !!k),
+  );
+  const multiRepo = repos.size > 1;
+
+  const entries: TreeEntry[] = [];
+  const toFile = new Map<string, string>();
+  const toDisplay = new Map<string, string>();
+  for (const c of withFiles) {
+    const ownerName = multiRepo ? purlOwnerName(c.purl) : undefined;
+    const displayPath = ownerName ? `${ownerName}/${c.file}` : c.file!;
+    if (toFile.has(displayPath)) continue;
+    entries.push({ displayPath, file: c.file! });
+    toFile.set(displayPath, c.file!);
+    if (!toDisplay.has(c.file!)) toDisplay.set(c.file!, displayPath);
+  }
+  return { entries, multiRepo, toFile, toDisplay };
+}
+
+// ---------------------------------------------------------------------------
+// Per-repo tree grouping — one sidebar tree per repo, each under its own
+// styled header (owner avatar + repo name).
+// ---------------------------------------------------------------------------
+
+export interface RepoGroup {
+  /** Purl repo key (`pkg:github/owner/name`) — undefined for purl-less components. */
+  repoKey?: string;
+  /** `owner` segment of the purl, when present. */
+  owner?: string;
+  /** Repository name segment of the purl, when present. */
+  repo?: string;
+  /** The group's files, bare `file` values (each tree scopes its own paths). */
+  entries: TreeEntry[];
+}
+
+/**
+ * Group components by repo for the multi-tree sidebar. Groups preserve
+ * first-appearance order; purl-less components land in a trailing unbadged
+ * group. Entries carry bare `file` values — separate trees scope their own
+ * path sets, so no synthetic prefixes are needed.
+ */
+export function buildRepoGroups(components: ReadonlyArray<{ file?: string; purl?: string }>): {
+  multiRepo: boolean;
+  groups: RepoGroup[];
+} {
+  const withFiles = components.filter((c) => c.file);
+  const repos = new Set(
+    withFiles.map((c) => purlRepoKey(c.purl)).filter((k): k is string => !!k),
+  );
+  const multiRepo = repos.size > 1;
+
+  const byKey = new Map<string, RepoGroup>();
+  const order: Array<string | undefined> = [];
+  for (const c of withFiles) {
+    const key = purlRepoKey(c.purl);
+    let group = byKey.get(key ?? '');
+    if (!group) {
+      const ownerName = key ? purlOwnerName(c.purl) : undefined;
+      const [owner, repo] = ownerName?.split('/') ?? [];
+      group = { repoKey: key, owner, repo, entries: [] };
+      byKey.set(key ?? '', group);
+      order.push(key);
+    }
+    if (!group.entries.some((e) => e.file === c.file)) {
+      group.entries.push({ displayPath: c.file!, file: c.file! });
+    }
+  }
+  return { multiRepo, groups: order.map((k) => byKey.get(k ?? '')!) };
+}
+
+/** GitHub owner-avatar URL for a purl, or undefined for non-github hosts. */
+export function repoAvatarUrl(purl: string | undefined): string | undefined {
+  const key = purlRepoKey(purl);
+  const match = key?.match(/^pkg:github\/([^/]+)\//);
+  return match ? `https://github.com/${match[1]}.png?size=64` : undefined;
+}

package/src/subsystem/tokenizeComponent.ts

@@ -0,0 +1,70 @@
+/**
+ * Tokenize a SubsystemComponent into a flat token stream for the detail panel.
+ *
+ * Pipeline: generate declaration string → format with Prettier → tokenize
+ * with Shiki + Pierre themes. The `component.tokens` field, when present,
+ * overrides the entire pipeline (for pre-tokenized data from graphify).
+ *
+ * This function is async because Prettier's format() is async.
+ */
+
+import type { PierreSyntaxThemeName } from '../pierre/pierreSyntaxTheme';
+import type { SubsystemComponent, SubsystemDeclToken } from './model';
+import { generateDeclarationString } from './formatDeclaration';
+import { tokenizeFormatted } from './tokenizeFormatted';
+
+// Lazy-loaded Prettier to avoid startup cost.
+let prettierPromise: Promise<typeof import('prettier/standalone')> | null = null;
+let prettierPluginsPromise: Promise<{
+  typescript: typeof import('prettier/plugins/typescript');
+  estree: typeof import('prettier/plugins/estree');
+}> | null = null;
+
+async function getPrettier() {
+  if (!prettierPromise) {
+    prettierPromise = import('prettier/standalone');
+  }
+  if (!prettierPluginsPromise) {
+    prettierPluginsPromise = Promise.all([
+      import('prettier/plugins/typescript'),
+      import('prettier/plugins/estree'),
+    ]).then(([typescript, estree]) => ({ typescript, estree }));
+  }
+  const [prettier, plugins] = await Promise.all([prettierPromise, prettierPluginsPromise]);
+  return { prettier, plugins };
+}
+
+/**
+ * Tokenize a SubsystemComponent into SubsystemDeclToken[].
+ *
+ * When `component.tokens` is present (pre-tokenized data from the wire),
+ * it's returned as-is. Otherwise the pipeline generates a TypeScript
+ * declaration string, formats it with Prettier, and tokenizes the output.
+ */
+export async function tokenizeComponent(
+  component: SubsystemComponent,
+  printWidth = 80,
+  themeName: PierreSyntaxThemeName = 'pierre-dark',
+): Promise<SubsystemDeclToken[]> {
+  // Pre-tokenized tokens from the wire take precedence.
+  if (component.tokens) return component.tokens;
+
+  // External kind — not valid TypeScript, bypass Prettier.
+  const kind = component.detail?.kind ?? component.construct;
+  if (kind === 'external') {
+    const label = component.detail?.kind === 'external' ? component.detail.label : component.name;
+    const escaped = label.replace(/\\/g, '\\\\').replace(/'/g, "\\'");
+    return tokenizeFormatted(`external '${escaped}'`, themeName);
+  }
+
+  // Generate → format → tokenize
+  const raw = generateDeclarationString(component);
+  const { prettier, plugins } = await getPrettier();
+  const formatted = await prettier.format(raw, {
+    parser: 'typescript',
+    plugins: [plugins.typescript, plugins.estree],
+    printWidth,
+  });
+
+  return tokenizeFormatted(formatted, themeName);
+}

package/src/subsystem/tokenizeFormatted.ts

@@ -0,0 +1,19 @@
+/**
+ * Tokenize a formatted TypeScript declaration string into SubsystemDeclToken[]
+ * using Shiki + Pierre themes (same highlighter stack as @pierre/diffs).
+ */
+
+import { tokenizeWithPierreSyntax } from '../pierre/syntaxTokens';
+import type { PierreSyntaxThemeName } from '../pierre/pierreSyntaxTheme';
+import type { SubsystemDeclToken } from './model';
+
+/**
+ * Tokenize a formatted TypeScript string into SubsystemDeclToken[].
+ * The input should already be formatted by Prettier (or be valid TS).
+ */
+export function tokenizeFormatted(
+  code: string,
+  themeName: PierreSyntaxThemeName = 'pierre-dark',
+): Promise<SubsystemDeclToken[]> {
+  return tokenizeWithPierreSyntax(code, themeName);
+}

package/src/utils/animationMapping.ts

@@ -0,0 +1,166 @@
+/**
+ * Animation mapping utilities
+ *
+ * Maps log levels and component events to appropriate animations
+ * for Milestone 1 default visualization behavior
+ */
+
+import type { LogLevel } from '@principal-ai/subsystems-core';
+
+/**
+ * Node animation configuration
+ */
+export interface NodeAnimation {
+  type: 'pulse' | 'flash' | 'shake' | 'entry';
+  duration: number;
+  intensity?: number; // 0-1 scale
+  color?: string;
+}
+
+/**
+ * Edge animation configuration
+ */
+export interface EdgeAnimation {
+  type: 'flow' | 'particle' | 'pulse' | 'glow';
+  duration: number;
+  direction?: 'forward' | 'backward' | 'bidirectional';
+  color?: string;
+}
+
+/**
+ * Map log level to node animation
+ *
+ * Default behavior for Milestone 1:
+ * - debug: subtle pulse (low intensity)
+ * - info: standard pulse (medium intensity)
+ * - warn: amber pulse (high intensity)
+ * - error: red flash + shake
+ */
+export function logLevelToNodeAnimation(level: LogLevel): NodeAnimation {
+  switch (level) {
+    case 'debug':
+      return {
+        type: 'pulse',
+        duration: 800,
+        intensity: 0.3,
+        color: '#94a3b8', // slate-400
+      };
+
+    case 'info':
+      return {
+        type: 'pulse',
+        duration: 1000,
+        intensity: 0.5,
+        color: '#3b82f6', // blue-500
+      };
+
+    case 'warn':
+      return {
+        type: 'pulse',
+        duration: 1200,
+        intensity: 1.0,
+        color: '#f59e0b', // amber-500
+      };
+
+    case 'error':
+      return {
+        type: 'flash', // More dramatic animation for errors
+        duration: 1500,
+        intensity: 1.0,
+        color: '#ef4444', // red-500
+      };
+  }
+}
+
+/**
+ * Map component action to node animation (Milestone 2)
+ */
+export function actionToNodeAnimation(_action: string, state?: string): NodeAnimation {
+  // Default mapping - can be overridden by configuration
+  switch (state) {
+    case 'acquired':
+    case 'active':
+    case 'processing':
+      return {
+        type: 'pulse',
+        duration: 1000,
+        intensity: 0.8,
+        color: '#22c55e', // green-500
+      };
+
+    case 'waiting':
+    case 'pending':
+      return {
+        type: 'pulse',
+        duration: 1500,
+        intensity: 0.5,
+        color: '#eab308', // yellow-500
+      };
+
+    case 'error':
+    case 'failed':
+      return {
+        type: 'shake',
+        duration: 600,
+        intensity: 1.0,
+        color: '#ef4444', // red-500
+      };
+
+    case 'completed':
+    case 'success':
+      return {
+        type: 'flash',
+        duration: 800,
+        intensity: 0.7,
+        color: '#22c55e', // green-500
+      };
+
+    default:
+      // Generic action animation
+      return {
+        type: 'pulse',
+        duration: 1000,
+        intensity: 0.6,
+        color: '#3b82f6', // blue-500
+      };
+  }
+}
+
+/**
+ * Get animation config for edge based on action (Milestone 2)
+ */
+export function actionToEdgeAnimation(_action: string, edgeConfig?: EdgeAnimation): EdgeAnimation {
+  // Use edge config if provided, otherwise default
+  return (
+    edgeConfig || {
+      type: 'flow',
+      duration: 2000,
+      direction: 'forward',
+    }
+  );
+}
+
+/**
+ * Check if log level should trigger animation
+ */
+export function shouldAnimate(level: LogLevel, minLevel: LogLevel = 'info'): boolean {
+  const levels: LogLevel[] = ['debug', 'info', 'warn', 'error'];
+  const minIndex = levels.indexOf(minLevel);
+  const currentIndex = levels.indexOf(level);
+
+  return currentIndex >= minIndex;
+}
+
+/**
+ * Calculate animation intensity based on frequency
+ * Used to adjust animation intensity when multiple logs occur rapidly
+ */
+export function calculateIntensity(
+  baseIntensity: number,
+  eventCount: number,
+  _timeWindow: number = 1000
+): number {
+  // Reduce intensity if too many events in time window
+  const scaleFactor = Math.min(1.0, 5.0 / eventCount);
+  return Math.max(0.2, baseIntensity * scaleFactor);
+}

package/src/utils/canvasBounds.ts

@@ -0,0 +1,146 @@
+import type { ExtendedCanvas } from '@principal-ai/subsystems-core';
+
+export interface CanvasBounds {
+  minX: number;
+  minY: number;
+  maxX: number;
+  maxY: number;
+  width: number;
+  height: number;
+}
+
+const DEFAULT_NODE_WIDTH = 200;
+const DEFAULT_NODE_HEIGHT = 100;
+
+/**
+ * Calculate the bounding box of all nodes in a canvas.
+ * Returns the min/max coordinates and total dimensions.
+ */
+export function getCanvasBounds(canvas: ExtendedCanvas): CanvasBounds {
+  if (!canvas.nodes || canvas.nodes.length === 0) {
+    return {
+      minX: 0,
+      minY: 0,
+      maxX: DEFAULT_NODE_WIDTH,
+      maxY: DEFAULT_NODE_HEIGHT,
+      width: DEFAULT_NODE_WIDTH,
+      height: DEFAULT_NODE_HEIGHT,
+    };
+  }
+
+  let minX = Infinity;
+  let minY = Infinity;
+  let maxX = -Infinity;
+  let maxY = -Infinity;
+
+  for (const node of canvas.nodes) {
+    const x = node.x ?? 0;
+    const y = node.y ?? 0;
+    const width = node.width ?? DEFAULT_NODE_WIDTH;
+    const height = node.height ?? DEFAULT_NODE_HEIGHT;
+
+    minX = Math.min(minX, x);
+    minY = Math.min(minY, y);
+    maxX = Math.max(maxX, x + width);
+    maxY = Math.max(maxY, y + height);
+  }
+
+  return {
+    minX,
+    minY,
+    maxX,
+    maxY,
+    width: maxX - minX,
+    height: maxY - minY,
+  };
+}
+
+export interface Viewport {
+  x: number;
+  y: number;
+  zoom: number;
+}
+
+/**
+ * Calculate the initial viewport to fit all nodes within a container.
+ * This allows setting defaultViewport on ReactFlow to avoid the
+ * "zoom in then animate out" effect.
+ *
+ * @param bounds - The bounding box of all nodes
+ * @param containerWidth - Width of the container in pixels
+ * @param containerHeight - Height of the container in pixels
+ * @param options - Additional options for padding and zoom limits
+ * @returns The viewport { x, y, zoom } to pass to ReactFlow's defaultViewport
+ */
+export function calculateInitialViewport(
+  bounds: CanvasBounds,
+  containerWidth: number,
+  containerHeight: number,
+  options: {
+    padding?: number;
+    minZoom?: number;
+    maxZoom?: number;
+  } = {}
+): Viewport {
+  const { padding = 0.2, minZoom = 0.1, maxZoom = 1.5 } = options;
+
+  // Calculate the zoom level needed to fit the bounds within the container
+  // Account for padding by reducing the effective container size
+  const effectiveWidth = containerWidth * (1 - padding);
+  const effectiveHeight = containerHeight * (1 - padding);
+
+  const zoomX = effectiveWidth / bounds.width;
+  const zoomY = effectiveHeight / bounds.height;
+
+  // Use the smaller zoom to ensure both dimensions fit
+  let zoom = Math.min(zoomX, zoomY);
+
+  // Clamp to min/max zoom
+  zoom = Math.max(minZoom, Math.min(maxZoom, zoom));
+
+  // Calculate the center of the bounds
+  const boundsCenterX = bounds.minX + bounds.width / 2;
+  const boundsCenterY = bounds.minY + bounds.height / 2;
+
+  // Calculate viewport position to center the bounds
+  // ReactFlow viewport x,y represent the offset of the canvas origin from the container's top-left
+  const x = containerWidth / 2 - boundsCenterX * zoom;
+  const y = containerHeight / 2 - boundsCenterY * zoom;
+
+  return { x, y, zoom };
+}
+
+/**
+ * Calculate a recommended display size for a canvas cell.
+ * Adds padding and enforces minimum dimensions.
+ */
+export function getCanvasDisplaySize(
+  canvas: ExtendedCanvas,
+  options: {
+    padding?: number;
+    minWidth?: number;
+    minHeight?: number;
+    maxWidth?: number;
+    maxHeight?: number;
+  } = {}
+): { width: number; height: number } {
+  const {
+    padding = 100,
+    minWidth = 300,
+    minHeight = 200,
+    maxWidth = 1200,
+    maxHeight = 800,
+  } = options;
+
+  const bounds = getCanvasBounds(canvas);
+
+  // Add padding to content dimensions
+  const contentWidth = bounds.width + padding * 2;
+  const contentHeight = bounds.height + padding * 2;
+
+  // Clamp to min/max
+  const width = Math.min(maxWidth, Math.max(minWidth, contentWidth));
+  const height = Math.min(maxHeight, Math.max(minHeight, contentHeight));
+
+  return { width, height };
+}