@principal-ai/subsystems-react 0.17.0

package/src/pierre/pierreFileLang.test.ts

@@ -0,0 +1,26 @@
+import { describe, expect, test } from 'bun:test';
+import {
+  isPierreCFamilyPath,
+  pierreCodeViewFileName,
+  pierreLangForPath,
+} from './pierreFileLang';
+
+describe('pierreFileLang', () => {
+  test('marks C-family extensions', () => {
+    expect(isPierreCFamilyPath('src/main.cpp')).toBe(true);
+    expect(isPierreCFamilyPath('src/graph.h')).toBe(true);
+    expect(isPierreCFamilyPath('foo.mm')).toBe(true);
+    expect(isPierreCFamilyPath('src/main.ts')).toBe(false);
+  });
+
+  test('forces plain text for C-family (WebKit-safe)', () => {
+    expect(pierreLangForPath('src/main.cpp')).toBe('text');
+    expect(pierreLangForPath('src/ingest_crawl.h')).toBe('text');
+    expect(pierreLangForPath('src/foo.ts')).toBeUndefined();
+  });
+
+  test('uniquifies CodeView names while keeping the extension', () => {
+    expect(pierreCodeViewFileName('src/main.cpp', 0)).toBe('01-main.cpp');
+    expect(pierreCodeViewFileName('src/main.cpp', 6)).toBe('07-main.cpp');
+  });
+});

package/src/pierre/pierreFileLang.ts

@@ -0,0 +1,55 @@
+/**
+ * Language overrides for `@pierre/diffs` file rendering.
+ *
+ * Pierre's default extension map sends `.h` → `objective-cpp`. Loading
+ * C-family Shiki grammars (`cpp` / `objective-cpp`) in CodeView has trapped
+ * WebKit (`JSString::getIndex` / EXC_BREAKPOINT) — even with unique per-step
+ * `file.name`s — so we force plain text for those paths until Pierre/WebKit
+ * is safe with them.
+ *
+ * Distinct throughline slices of the same path still need unique `file.name`s
+ * (see `pierreCodeViewFileName`).
+ */
+
+const C_FAMILY_EXT = new Set([
+  'c',
+  'h',
+  'cc',
+  'cpp',
+  'cxx',
+  'hpp',
+  'hh',
+  'mm',
+  'm',
+]);
+
+function extensionOf(path: string): string {
+  const base = path.split(/[/\\]/).pop() ?? path;
+  const dot = base.lastIndexOf('.');
+  if (dot < 0) return '';
+  return base.slice(dot + 1).toLowerCase();
+}
+
+/** True when Pierre would (or we would) treat this path as C-family source. */
+export function isPierreCFamilyPath(path: string): boolean {
+  return C_FAMILY_EXT.has(extensionOf(path));
+}
+
+/**
+ * Explicit `lang` for a Pierre `FileContents` object.
+ *
+ * - C-family → `'text'` (WebKit-safe; no cpp/obj-c++ Shiki grammar)
+ * - everything else → `undefined` (Pierre infers from the filename)
+ */
+export function pierreLangForPath(path: string): 'text' | undefined {
+  return isPierreCFamilyPath(path) ? 'text' : undefined;
+}
+
+/**
+ * Unique CodeView `file.name` that still carries a real extension for
+ * inference, so distinct slices of the same path never share a display name.
+ */
+export function pierreCodeViewFileName(path: string, index: number): string {
+  const base = path.split(/[/\\]/).pop() ?? path;
+  return `${String(index + 1).padStart(2, '0')}-${base}`;
+}

package/src/pierre/pierreSyntaxTheme.ts

@@ -0,0 +1,23 @@
+/**
+ * Pierre syntax theme names — aligned with @pierre/diffs DEFAULT_THEMES.
+ */
+
+export type PierreSyntaxThemeName = 'pierre-dark' | 'pierre-light';
+
+export const PIERRE_DEFAULT_SYNTAX_THEMES = {
+  dark: 'pierre-dark',
+  light: 'pierre-light',
+} as const satisfies Record<'dark' | 'light', PierreSyntaxThemeName>;
+
+/** Pick pierre-dark / pierre-light to match Pierre file views and industry-theme mode. */
+export function resolvePierreSyntaxThemeName(mode?: string): PierreSyntaxThemeName {
+  if (mode === 'light') return PIERRE_DEFAULT_SYNTAX_THEMES.light;
+  if (mode === 'dark') return PIERRE_DEFAULT_SYNTAX_THEMES.dark;
+  if (
+    typeof window !== 'undefined' &&
+    window.matchMedia('(prefers-color-scheme: light)').matches
+  ) {
+    return PIERRE_DEFAULT_SYNTAX_THEMES.light;
+  }
+  return PIERRE_DEFAULT_SYNTAX_THEMES.dark;
+}

package/src/pierre/scrollAnchor.test.ts

@@ -0,0 +1,13 @@
+import { describe, expect, test } from 'bun:test';
+import { scrollAnchorLine } from './scrollAnchor';
+
+describe('scrollAnchorLine', () => {
+  test('first line stays at top', () => {
+    expect(scrollAnchorLine(1)).toBe(1);
+  });
+
+  test('focus line keeps a few lines of leading context', () => {
+    expect(scrollAnchorLine(10, 4)).toBe(6);
+    expect(scrollAnchorLine(3, 4)).toBe(1);
+  });
+});

package/src/pierre/scrollAnchor.ts

@@ -0,0 +1,11 @@
+/** Lines to keep visible above the focus line when scrolling. */
+export const SCROLL_LEADING_LINES = 4;
+
+/** 1-based line in the sliced snippet to align near the top of the viewport. */
+export function scrollAnchorLine(
+  focusOffset: number,
+  leadingLines = SCROLL_LEADING_LINES,
+): number {
+  if (focusOffset <= 1) return 1;
+  return Math.max(1, focusOffset - leadingLines);
+}

package/src/pierre/sliceSnippet.test.ts

@@ -0,0 +1,21 @@
+import { describe, expect, test } from 'bun:test';
+import { sliceSnippetWindow } from './sliceSnippet';
+
+describe('sliceSnippetWindow', () => {
+  const content = ['line1', 'line2', 'line3', 'line4', 'line5'].join('\n');
+
+  test('slices with context and focus offset', () => {
+    const s = sliceSnippetWindow(content, 3, 3, 1, 3);
+    expect(s.sliceStart).toBe(2);
+    expect(s.sliceEnd).toBe(4);
+    expect(s.contents).toBe(['line2', 'line3', 'line4'].join('\n'));
+    expect(s.focusOffset).toBe(2);
+  });
+
+  test('clamps out-of-range lines', () => {
+    const s = sliceSnippetWindow(content, 99, 99, 0, 99);
+    expect(s.sliceStart).toBe(5);
+    expect(s.sliceEnd).toBe(5);
+    expect(s.focusOffset).toBe(95);
+  });
+});

package/src/pierre/sliceSnippet.ts

@@ -0,0 +1,31 @@
+/** Slice a file's line range with surrounding context for snippet rendering. */
+
+export interface SnippetSlice {
+  contents: string;
+  sliceStart: number;
+  sliceEnd: number;
+  /** 1-based line index within `contents` to highlight, or null. */
+  focusOffset: number | null;
+}
+
+export function sliceSnippetWindow(
+  contents: string,
+  startLine: number,
+  endLine: number,
+  contextLines: number,
+  focusLine?: number | null,
+): SnippetSlice {
+  const allLines = contents.split('\n');
+  const total = allLines.length;
+  const safeStart = Math.max(1, Math.min(startLine, total));
+  const safeEnd = Math.max(safeStart, Math.min(endLine, total));
+  const sliceStart = Math.max(1, safeStart - contextLines);
+  const sliceEnd = Math.min(total, safeEnd + contextLines);
+  return {
+    contents: allLines.slice(sliceStart - 1, sliceEnd).join('\n'),
+    sliceStart,
+    sliceEnd,
+    focusOffset:
+      focusLine == null ? null : Math.max(1, focusLine - sliceStart + 1),
+  };
+}

package/src/pierre/syntaxTokens.test.ts

@@ -0,0 +1,35 @@
+import { describe, expect, test } from 'bun:test';
+import { tokenizeWithPierreSyntax } from './syntaxTokens';
+
+describe('tokenizeWithPierreSyntax', () => {
+  test('assigns Pierre dark keyword and type colors', async () => {
+    const tokens = await tokenizeWithPierreSyntax(
+      'export class Foo extends Bar {}',
+      'pierre-dark',
+    );
+    const joined = tokens.filter((t) => t.kind !== 'newline').map((t) => t.text).join('');
+    expect(joined).toBe('export class Foo extends Bar {}');
+
+    const exportTok = tokens.find((t) => t.text === 'export');
+    const classTok = tokens.find((t) => t.text === 'class');
+    const fooTok = tokens.find((t) => t.text === 'Foo');
+    const barTok = tokens.find((t) => t.text === 'Bar');
+
+    expect(exportTok?.color).toBe('#ff678d');
+    expect(classTok?.color).toBe('#d568ea');
+    expect(fooTok?.color).toBe('#d568ea');
+    expect(barTok?.color).toBe('#d568ea');
+  });
+
+  test('light theme resolves different palette than dark', async () => {
+    const [dark, light] = await Promise.all([
+      tokenizeWithPierreSyntax('const x = 1', 'pierre-dark'),
+      tokenizeWithPierreSyntax('const x = 1', 'pierre-light'),
+    ]);
+    const darkConst = dark.find((t) => t.text === 'const');
+    const lightConst = light.find((t) => t.text === 'const');
+    expect(darkConst?.color).toBeTruthy();
+    expect(lightConst?.color).toBeTruthy();
+    expect(darkConst?.color).not.toBe(lightConst?.color);
+  });
+});

package/src/pierre/syntaxTokens.ts

@@ -0,0 +1,60 @@
+/**
+ * Tokenize TypeScript with Shiki + Pierre themes — same stack as @pierre/diffs.
+ */
+
+import { createHighlighter, type Highlighter, type ThemeInput } from 'shiki';
+import pierreDark from '@pierre/theme/pierre-dark';
+import pierreLight from '@pierre/theme/pierre-light';
+import type { SubsystemDeclToken } from '../subsystem/model';
+import type { PierreSyntaxThemeName } from './pierreSyntaxTheme';
+
+let highlighterPromise: Promise<Highlighter> | null = null;
+
+async function getPierreHighlighter(): Promise<Highlighter> {
+  if (!highlighterPromise) {
+    highlighterPromise = createHighlighter({
+      themes: [
+        pierreDark as unknown as ThemeInput,
+        pierreLight as unknown as ThemeInput,
+      ],
+      langs: ['typescript'],
+    });
+  }
+  return highlighterPromise;
+}
+
+function normalizeColor(color?: string): string | undefined {
+  return color?.toLowerCase();
+}
+
+/**
+ * Tokenize formatted TypeScript using Pierre's Shiki themes.
+ * Each token carries the resolved foreground color Pierre would render.
+ */
+export async function tokenizeWithPierreSyntax(
+  code: string,
+  themeName: PierreSyntaxThemeName,
+): Promise<SubsystemDeclToken[]> {
+  const highlighter = await getPierreHighlighter();
+  const { tokens } = highlighter.codeToTokens(code, {
+    lang: 'typescript',
+    theme: themeName,
+  });
+
+  const result: SubsystemDeclToken[] = [];
+  for (let lineIndex = 0; lineIndex < tokens.length; lineIndex++) {
+    const line = tokens[lineIndex];
+    for (const token of line) {
+      if (!token.content) continue;
+      result.push({
+        text: token.content,
+        kind: 'punctuation',
+        color: normalizeColor(token.color),
+      });
+    }
+    if (lineIndex < tokens.length - 1) {
+      result.push({ text: '', kind: 'newline' });
+    }
+  }
+  return result;
+}

package/src/stories/Audit/BoundaryNodes.stories.tsx

@@ -0,0 +1,385 @@
+import React from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import { GraphRenderer } from '../../components/GraphRenderer';
+import type { ExtendedCanvas } from '@principal-ai/subsystems-core';
+import { ThemeProvider, defaultEditorTheme } from '@principal-ade/industry-theme';
+
+const meta = {
+  title: 'Audit/BoundaryNodes',
+  component: GraphRenderer,
+  parameters: {
+    layout: 'centered',
+  },
+  tags: ['autodocs'],
+  decorators: [
+    (Story) => (
+      <ThemeProvider theme={defaultEditorTheme}>
+        <Story />
+      </ThemeProvider>
+    ),
+  ],
+} satisfies Meta<typeof GraphRenderer>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+/**
+ * Canvas showing boundary node visual treatment
+ */
+const boundaryNodesCanvas: ExtendedCanvas = {
+  nodes: [
+    // Regular node for comparison
+    {
+      id: 'regular-node',
+      type: 'text',
+      x: 100,
+      y: 100,
+      width: 160,
+      height: 80,
+      text: '# Regular Node\nSharp corners',
+      color: 6, // purple
+      pv: {
+        nodeType: 'event',
+        name: 'Regular Node',
+        description: 'A standard event node with sharp corners',
+        sources: ['src/events/regular.ts'],
+        event: {
+          name: 'app.regular-event',
+          description: 'Regular event',
+          attributes: {},
+        },
+      },
+    },
+    // Outbound boundary node
+    {
+      id: 'outbound-boundary',
+      type: 'text',
+      x: 350,
+      y: 100,
+      width: 180,
+      height: 80,
+      text: '# Host Callback\nPersists layout',
+      color: 5, // cyan
+      pv: {
+        nodeType: 'boundary',
+        name: 'onBatchLayoutInitialized',
+        description: 'Calls host to persist batch layout data',
+        boundary: {
+          direction: 'outbound',
+          node: {
+            'pv.event.name': 'host.batch-layout-initialized',
+            'pv.event.namespace': 'collection-host',
+          },
+        },
+      },
+    },
+    // Inbound boundary node
+    {
+      id: 'inbound-boundary',
+      type: 'text',
+      x: 620,
+      y: 100,
+      width: 180,
+      height: 80,
+      text: '# Webhook\nRepository created',
+      color: 5, // cyan
+      pv: {
+        nodeType: 'boundary',
+        name: 'onRepositoryCreated',
+        description: 'Called by GitHub when a repository is created',
+        boundary: {
+          direction: 'inbound',
+          node: {
+            'pv.event.name': 'webhook.repository-created',
+            'pv.event.namespace': 'github',
+          },
+        },
+      },
+    },
+  ],
+  edges: [],
+  pv: {
+    version: '1.0.0',
+    name: 'Boundary Nodes Demo',
+    description: 'Demonstrates boundary node visual treatment',
+    edgeTypes: {},
+  },
+};
+
+export const BoundaryVsRegular: Story = {
+  args: {
+    canvas: boundaryNodesCanvas,
+    width: 900,
+    height: 300,
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: `
+**Boundary Node Visual Treatment**
+
+Boundary nodes represent interaction points where control crosses system edges.
+They have distinct visual treatment:
+
+- **Rounded corners** (8px border-radius) to visually distinguish from regular nodes
+- **Direction badge** in top-right corner:
+  - ↗ (arrow up-right) for **outbound** boundaries - this system calls external
+  - ↙ (arrow down-left) for **inbound** boundaries - external calls this system
+- **Cyan badge color** (#06b6d4) to match boundary theme
+- **No sources badge** since boundary nodes don't have local source files
+
+Compare with the regular node on the left which has:
+- Sharp corners (0 border-radius)
+- Green "S" sources badge (when sources are defined)
+        `,
+      },
+    },
+  },
+};
+
+/**
+ * Canvas showing boundary nodes in a workflow context
+ */
+const workflowWithBoundariesCanvas: ExtendedCanvas = {
+  nodes: [
+    // Internal event
+    {
+      id: 'batch-save',
+      type: 'text',
+      x: 100,
+      y: 150,
+      width: 160,
+      height: 70,
+      text: '# Batch Save\nSaves regions',
+      color: 4, // green
+      pv: {
+        nodeType: 'event',
+        name: 'batch-save',
+        event: {
+          name: 'collection-map.batch-save',
+          description: 'Saved regions to local state',
+          attributes: {},
+        },
+      },
+    },
+    // Outbound to host
+    {
+      id: 'host-persist',
+      type: 'text',
+      x: 350,
+      y: 150,
+      width: 180,
+      height: 70,
+      text: '# Host: Persist\nSaves to backend',
+      color: 5, // cyan
+      pv: {
+        nodeType: 'boundary',
+        name: 'onBatchLayoutInitialized',
+        boundary: {
+          direction: 'outbound',
+          node: {
+            'pv.event.name': 'host.batch-layout-initialized',
+          },
+        },
+      },
+    },
+    // Another internal event
+    {
+      id: 'layout-complete',
+      type: 'text',
+      x: 620,
+      y: 150,
+      width: 160,
+      height: 70,
+      text: '# Layout Complete\nUI updated',
+      color: 4, // green
+      pv: {
+        nodeType: 'event',
+        name: 'layout-complete',
+        event: {
+          name: 'collection-map.layout-complete',
+          description: 'Layout computation finished',
+          attributes: {},
+        },
+      },
+    },
+  ],
+  edges: [
+    {
+      id: 'e1',
+      fromNode: 'batch-save',
+      toNode: 'host-persist',
+      fromSide: 'right',
+      toSide: 'left',
+    },
+    {
+      id: 'e2',
+      fromNode: 'host-persist',
+      toNode: 'layout-complete',
+      fromSide: 'right',
+      toSide: 'left',
+    },
+  ],
+  pv: {
+    version: '1.0.0',
+    name: 'Workflow with Boundaries',
+    description: 'Shows boundary nodes in workflow context',
+    edgeTypes: {
+      default: {
+        style: 'solid',
+        color: '#888',
+        directed: true,
+      },
+    },
+  },
+};
+
+export const WorkflowContext: Story = {
+  args: {
+    canvas: workflowWithBoundariesCanvas,
+    width: 900,
+    height: 350,
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: `
+**Boundary Nodes in Workflow Context**
+
+This shows how boundary nodes appear in a typical workflow:
+
+1. **Internal Event** (green, sharp corners) - Code we own and instrument
+2. **Boundary Node** (cyan, rounded corners) - Calls external system
+3. **Internal Event** (green, sharp corners) - Continues after external call
+
+The boundary node visually breaks the flow to indicate control leaving the system.
+The ↗ badge indicates this is an outbound call (we call them, they don't call us).
+        `,
+      },
+    },
+  },
+};
+
+/**
+ * Canvas showing different boundary directions
+ */
+const boundaryDirectionsCanvas: ExtendedCanvas = {
+  nodes: [
+    // Outbound examples
+    {
+      id: 'outbound-1',
+      type: 'text',
+      x: 100,
+      y: 100,
+      width: 180,
+      height: 70,
+      text: '# Host Callback\nonBatchLayout',
+      color: 5,
+      pv: {
+        nodeType: 'boundary',
+        name: 'onBatchLayout',
+        boundary: {
+          direction: 'outbound',
+          node: { 'pv.event.name': 'host.batch-layout' },
+        },
+      },
+    },
+    {
+      id: 'outbound-2',
+      type: 'text',
+      x: 350,
+      y: 100,
+      width: 180,
+      height: 70,
+      text: '# API Call\nPOST /payments',
+      color: 5,
+      pv: {
+        nodeType: 'boundary',
+        name: 'createPayment',
+        boundary: {
+          direction: 'outbound',
+          node: { 'pv.event.name': 'stripe.payment-created' },
+        },
+      },
+    },
+    // Inbound examples
+    {
+      id: 'inbound-1',
+      type: 'text',
+      x: 100,
+      y: 250,
+      width: 180,
+      height: 70,
+      text: '# Webhook\nrepo.created',
+      color: 5,
+      pv: {
+        nodeType: 'boundary',
+        name: 'onRepoCreated',
+        boundary: {
+          direction: 'inbound',
+          node: { 'pv.event.name': 'github.repo-created' },
+        },
+      },
+    },
+    {
+      id: 'inbound-2',
+      type: 'text',
+      x: 350,
+      y: 250,
+      width: 180,
+      height: 70,
+      text: '# Message\norder.placed',
+      color: 5,
+      pv: {
+        nodeType: 'boundary',
+        name: 'onOrderPlaced',
+        boundary: {
+          direction: 'inbound',
+          node: { 'pv.event.name': 'queue.order-placed' },
+        },
+      },
+    },
+  ],
+  edges: [],
+  pv: {
+    version: '1.0.0',
+    name: 'Boundary Directions',
+    description: 'Outbound vs Inbound boundary nodes',
+    edgeTypes: {},
+    nodeTypes: {
+      boundary: {
+        description: 'External system boundary',
+        color: '#06b6d4',
+      },
+    },
+  },
+};
+
+export const DirectionComparison: Story = {
+  args: {
+    canvas: boundaryDirectionsCanvas,
+    width: 650,
+    height: 400,
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: `
+**Outbound vs Inbound Boundaries**
+
+**Top row - Outbound (↗)**
+- Host callbacks we invoke
+- API calls we make
+- Messages we publish
+
+**Bottom row - Inbound (↙)**
+- Webhooks that call us
+- Queue messages we consume
+- Events we subscribe to
+
+The direction badge makes it immediately clear which way control flows across the boundary.
+        `,
+      },
+    },
+  },
+};