@principal-ai/principal-view-react 0.16.56 → 0.16.57

package/src/subsystem/model.ts

@@ -2,7 +2,7 @@
  * Subsystem component-graph data model + converters.
  *
  * A subsystem snapshot (see the "Subsystem artifact: facets" topic) is captured
- * as component nodes (kind-tagged source units), file refs, integration edges,
+ * as component nodes (construct-tagged source units), file refs, integration edges,
  * and entry points. This module defines the minimal document shape for the
  * *graph* facet and converts it to React Flow nodes/edges — packages render as
  * subgraphs, only cross-package edges leave the box, and shared seams
@@ -21,14 +21,30 @@ import { computeElkLayout } from '../utils/elkLayout';
 import type { GraphifyComponentDetail } from '../graphify';
 import type { SubsystemDeclarationRef } from './declarationRef';
 
-export type SubsystemComponentKind =
+export type SubsystemComponentConstruct =
   | 'class'
   | 'function'
   | 'method'
-  | 'type'
+  | 'interface'
+  | 'type_alias'
+  | 'enum'
   | 'module'
+  | 'store'
   | 'external';
 
+/**
+ * Semantic role — where the node sits in the topology, orthogonal to
+ * `construct` (what it is). Roles have *inherited* anatomy: an entry renders
+ * as its real code shape (function dispatcher, type contract); a service has
+ * no source at all (`construct: 'external'` + purl identity). Contrast with
+ * `construct: 'store'`, which introduces its own anatomy (the state block) —
+ * that is why store is a construct and not a role. Role nodes must stay anchored to real code: an
+ * `entry` is a boundary element (route dispatcher, message contract) carrying
+ * the wire address as identity; a `service` is an external system the process
+ * calls out to (identity via purl, no `process` — it belongs to no region).
+ */
+export type SubsystemComponentRole = 'entry' | 'service';
+
 // ---------------------------------------------------------------------------
 // Declaration tokens — structured source representation
 // ---------------------------------------------------------------------------
@@ -65,19 +81,48 @@ export type SubsystemEdgeMechanism =
   | 'contains'
   | 'feeds'
   | 'produces'
+  | 'writes'
+  | 'reads'
+  | 'watches'
   | 'registers-into';
 
-/** A component node — the named unit, kind-tagged; `file` is its location. */
+/** A component node — the named unit, construct-tagged; `file` is its location. */
 export interface SubsystemComponent {
   id: string;
   name: string;
-  kind: SubsystemComponentKind;
+  /**
+   * The node's construct — what it IS as a declaration (class, function,
+   * method, interface, type alias, enum, store, external), driving node
+   * anatomy, color, badge, and the verification strategy. Every construct
+   * anchors to a definition; runtime occurrences (variables, activations,
+   * instances) are NOT constructs — they belong to a future execution-mode
+   * graph whose occurrence nodes reference these definitions. Ontology:
+   * construct = what it is, role = where it sits, process = where it runs.
+   */
+  construct: SubsystemComponentConstruct;
   /** Source location the component lives in (repo-root-relative path). */
   file: string;
   /** PURL identifying the repo or package this component lives in (for subgraph grouping). */
   purl: string;
   /** One-line purpose shown on the node. */
   purpose?: string;
+  /**
+   * Semantic role — where the node sits in the topology (boundary element,
+   * external system), orthogonal to `construct` (what it is). Drives the
+   * glyph and the edge-pairing rules: boundary-crossing edges must terminate
+   * at an entry or a service. Retained state is NOT a role — it is
+   * `construct: 'store'` (state-block anatomy, `writes`/`reads`/`watches`
+   * inbound, `produces` outbound).
+   */
+  role?: SubsystemComponentRole;
+  /**
+   * Runtime process membership — which deployment unit this node is a
+   * member of (e.g. `trail-viewer/host`, `trail-viewer/renderer`). Nodes
+   * sharing a `process` are drawn inside one boundary region (grouping is
+   * `process ?? purl`); nodes without one sit outside every boundary
+   * (external actors, services, libraries).
+   */
+  process?: string;
   /** A symbol this component exposes / is (the node's identity). */
   symbol?: string;
   /**
@@ -96,7 +141,7 @@ export interface SubsystemComponent {
   capture?: 'edited' | 'analyzed' | 'referenced';
   /**
    * Graphify drill-down detail for this component, when the facet is anchored
-   * to a graphify node. Discriminated by kind (class/function/type/module/
+   * to a graphify node. Discriminated by kind (class/function/type/module/store/
    * external); rendered in the detail panel on click.
    */
   detail?: GraphifyComponentDetail;
@@ -133,10 +178,10 @@ export interface SubsystemComponentEdge {
 }
 
 /**
- * Derive a consistent display `name` from a code `symbol` + kind.
+ * Derive a consistent display `name` from a code `symbol` + construct.
  *
- * `symbol` is the source of truth (fully-qualified code identity). For most
- * kinds the name is the symbol itself or its last dotted segment:
+ * `symbol` is the source of truth (fully-qualified code identity). The name
+ * is the symbol itself:
  *  - class/type/module/function/script/...  symbol → symbol (e.g. `SessionReader`)
  *  - method                               `Owner.method` → last segment (e.g. `SessionReader.normalize` → `normalize`)
  *  - module, no symbol → basename of `file` (e.g. `transcript.ts` → `transcript`) —
@@ -145,20 +190,37 @@ export interface SubsystemComponentEdge {
  */
 export function deriveNameFromSymbol(
   symbol: string | undefined,
-  kind: SubsystemComponentKind,
+  construct: SubsystemComponentConstruct,
   existingName?: string,
   file?: string,
 ): string {
+  let name: string | undefined;
   if (symbol && symbol.trim()) {
-    return symbol;
-  }
-  // Module nodes without a symbol are whole files → use the file basename.
-  if (kind === 'module' && file) {
+    name = symbol;
+  } else if (construct === 'module' && file) {
     const base = file.split('/').pop() ?? '';
     const clean = base.replace(/\.[^.]+$/, ''); // strip extension
-    if (clean) return clean;
+    if (clean) name = clean;
+  }
+  if (!name) name = existingName ?? 'untitled';
+
+  // Decoration = what the drill-down shows. Executable constructs wear `()`
+  // (a signature you can call); brace-bodied constructs wear ` {}` (a member
+  // body — fields for types/interfaces/enums, fields+methods for classes).
+  // Everything else (store, variable, module, external) renders bare.
+  if ((construct === 'function' || construct === 'method') && !name.endsWith('()')) {
+    name = `${name}()`;
   }
-  return existingName ?? 'untitled';
+  if (
+    (construct === 'class' ||
+      construct === 'interface' ||
+      construct === 'type_alias' ||
+      construct === 'enum') &&
+    !name.endsWith('{}')
+  ) {
+    name = `${name} {}`;
+  }
+  return name;
 }
 
 /**
@@ -237,6 +299,9 @@ export const MECHANISM_COLOR: Record<SubsystemEdgeMechanism, string> = {
   contains: '#6c5ce7', // indigo
   feeds: '#22c55e', // green — data-flow into a processor
   produces: '#e07a5f', // terracotta — emits an output type
+  writes: '#2f9e44', // deep green — mutates retained state
+  reads: '#0ea5e9', // sky — pulls from retained state
+  watches: '#9ca3af', // gray — observes, owns nothing
   'registers-into': '#ff6b35', // orange
 };
 
@@ -256,6 +321,9 @@ export const MECHANISM_STYLE: Record<SubsystemEdgeMechanism, 'solid' | 'dashed'
   contains: 'solid',
   feeds: 'solid',
   produces: 'solid',
+  writes: 'solid',
+  reads: 'solid',
+  watches: 'dashed',
   'registers-into': 'dashed',
 };
 
@@ -274,14 +342,19 @@ export function packageColor(name: string): string {
   return palette[h % palette.length];
 }
 
-/** Color per component kind — the informative signal (rather than package). */
-export const KIND_COLOR: Record<SubsystemComponentKind, string> = {
-  class: '#0893d2', // blue
-  function: '#6c5ce7', // indigo
-  method: '#d4a03c', // gold
-  type: '#e07a5f', // terracotta
-  module: '#4ec9b0', // teal
-  external: '#b48ead', // purple
+/** Color per semantic role — applied ONLY to the role badge (top-right tab on
+ *  nodes that carry a role). The node border stays construct-colored. Note:
+ *  `service` currently equals the old class hex; harmless while role badges
+ *  are the only surface using it, but pick a distinct value if roles ever
+ *  take over node borders. */
+export const ROLE_COLOR: Record<SubsystemComponentRole, string> = {
+  entry: '#ff6b35', // orange — boundary element
+  service: '#0893d2', // blue — external system
+};
+
+export const ROLE_LABEL: Record<SubsystemComponentRole, string> = {
+  entry: 'entry',
+  service: 'service',
 };
 
 /**
@@ -297,12 +370,16 @@ export function convertSubsystemToNodes(
   opts: { maxNodeWidth?: number } = {},
 ): SubsystemGraphNode[] {
   const { maxNodeWidth } = opts;
-  // Group components by package.
+  // Group components into boundary regions by process when authored, else by
+  // package. Process is runtime membership (drawn as one boundary region);
+  // purl is code identity — nodes without a process (external actors,
+  // services, libraries) fall back to purl and sit outside every boundary.
   const byPkg = new Map<string, SubsystemComponent[]>();
   for (const c of doc.components) {
-    const list = byPkg.get(c.purl) ?? [];
+    const regionKey = c.process ?? c.purl;
+    const list = byPkg.get(regionKey) ?? [];
     list.push(c);
-    byPkg.set(c.purl, list);
+    byPkg.set(regionKey, list);
   }
 
   const nodes: SubsystemGraphNode[] = [];
@@ -322,7 +399,7 @@ export function convertSubsystemToNodes(
       const row = Math.floor(i / COLS);
       // Estimate rendered node width from the longest text line so ELK reserves
       // the right space (names can wrap, so we cap at the configurable max).
-      const text = [c.symbol, c.name, c.file.split('/').pop() ?? '']
+      const text = [c.symbol, c.name, c.file?.split('/').pop() ?? '']
         .filter((t): t is string => !!t)
         .sort((a, b) => b.length - a.length)[0];
       const cap = maxNodeWidth ?? 300;
@@ -387,8 +464,8 @@ export function subsystemGraphLayoutKey(
   doc: Pick<SubsystemGraphDocument, 'components' | 'edges'>,
 ): string {
   const components = doc.components
-    .map(({ id, purl, name, symbol, kind, file, purpose }) =>
-      [id, purl, name, symbol ?? '', kind, file, purpose ?? ''].join('\0'))
+    .map(({ id, purl, name, symbol, construct, file, purpose, process }) =>
+      [id, purl, name, symbol ?? '', construct, file, purpose ?? '', process ?? ''].join('\0'))
     .sort()
     .join('\n');
   const edgeKey = doc.edges
@@ -437,7 +514,7 @@ export async function buildSubsystemGraph(
         component: {
           id: extId,
           name: label,
-          kind: 'external',
+          construct: 'external',
           purl: 'external',
           file: '',
           purpose: 'cross-package integration target (not a member node)',

package/src/subsystem/nodes.tsx

@@ -16,18 +16,26 @@ import {
 } from '@xyflow/react';
 import { useTheme } from '@principal-ade/industry-theme';
 import {
-  KIND_COLOR,
   MECHANISM_COLOR,
+  MECHANISM_STYLE,
+  ROLE_COLOR,
+  ROLE_LABEL,
   deriveNameFromSymbol,
   type SubsystemGraphNode,
   type SubsystemGraphEdge,
 } from './model';
+import { constructColorsFromPierreTheme } from '../pierre/constructColors';
+import { resolvePierreSyntaxThemeName } from '../pierre/pierreSyntaxTheme';
 
-export const KIND_LABEL: Record<string, string> = {
+export const CONSTRUCT_LABEL: Record<string, string> = {
   class: 'class',
   function: 'function',
-  type: 'type',
+  method: 'method',
+  interface: 'interface',
+  type_alias: 'type alias',
+  enum: 'enum',
   module: 'module',
+  store: 'store',
   external: 'external',
 };
 
@@ -48,6 +56,9 @@ function breakWords(s: string): string {
 export interface SubsystemGraphCallbacks {
   /** Click a component — open its file/entry point. */
   onSelect?: (componentId: string) => void;
+  /** Click the filename badge — open that component's file in the drawer
+   *  (same path as clicking the file link in the declaration panel). */
+  onOpenFile?: (componentId: string) => void;
   /** Click an edge (or its label) — select the relationship. */
   onEdgeSelect?: (edgeId: string) => void;
   /** Hover a component (null on leave) — associates it with the file tree. */
@@ -60,15 +71,19 @@ export interface SubsystemGraphCallbacks {
 export const SUBSYSTEM_CALLBACKS: SubsystemGraphCallbacks = {};
 
 export function SubsystemComponentNode(props: NodeProps<SubsystemGraphNode>) {
-  const { theme } = useTheme();
+  const { theme, mode } = useTheme();
   const { data, selected, width: nodeWidth, height: nodeHeight } = props;
   const c = data.component;
-  const color = KIND_COLOR[c.kind] ?? '#888';
+  // Construct owns node color, derived from the active Pierre syntax theme —
+  // the same palette the declaration panel and file drawer render with. Role
+  // shows as the hover badge, not as color — for now; a role glyph/accent may
+  // come later.
+  const color = constructColorsFromPierreTheme(resolvePierreSyntaxThemeName(mode))[c.construct];
   const [hover, setHover] = useState(false);
   const configuredMax = SUBSYSTEM_CALLBACKS.maxNodeWidth;
   const maxWidth = configuredMax ?? 300;
   // `symbol` is the source of truth; `name` is derived from it consistently.
-  const displayName = deriveNameFromSymbol(c.symbol, c.kind, c.name, c.file);
+  const displayName = deriveNameFromSymbol(c.symbol, c.construct, c.name, c.file);
   // Set while a file is open in the drawer: true → spotlight, false → dim,
   // absent (no file open) → neutral.
   const fileMatch = data.fileMatch as boolean | undefined;
@@ -117,36 +132,91 @@ export function SubsystemComponentNode(props: NodeProps<SubsystemGraphNode>) {
         fontFamily: theme.fonts.body,
       }}
     >
-      {/* Kind + package tooltip, shown at the top on hover */}
-      {hover && (
+      {/* Construct badge — a small tab riding the top-right border, in the
+          construct color. Persistent (no hover needed); pointer-events none so
+          clicks pass through to the node. */}
+      <div
+        style={{
+          position: 'absolute',
+          top: -9,
+          left: 10,
+          zIndex: 1,
+          fontFamily: theme.fonts.monospace,
+          fontSize: theme.fontSizes[0] * 1.1,
+          letterSpacing: 0.5,
+          textTransform: 'uppercase',
+          lineHeight: '17px',
+          color,
+          background: theme.colors.backgroundSecondary ?? theme.colors.background,
+          border: `1px solid ${color}`,
+          borderRadius: 4,
+          padding: '0 5px',
+        }}
+      >
+        {CONSTRUCT_LABEL[c.construct] ?? c.construct}
+      </div>
+
+      {/* Role badge — top-right, only when the node carries a topology role.
+          Role color (entry orange / service blue) on the badge; the node
+          border stays construct-colored. */}
+      {c.role != null && (
         <div
           style={{
             position: 'absolute',
-            top: -26,
-            left: 0,
-            zIndex: 1000,
-            display: 'flex',
-            alignItems: 'center',
-            gap: 6,
-            whiteSpace: 'nowrap',
-            fontSize: theme.fontSizes[0] * 0.8,
+            top: -9,
+            right: 10,
+            zIndex: 1,
             fontFamily: theme.fonts.monospace,
+            fontSize: theme.fontSizes[0] * 1.1,
             letterSpacing: 0.5,
-            color,
-            background: theme.colors.background,
-            border: `1px solid ${theme.colors.border}`,
+            textTransform: 'uppercase',
+            lineHeight: '17px',
+            color: ROLE_COLOR[c.role],
+            background: theme.colors.backgroundSecondary ?? theme.colors.background,
+            border: `1px solid ${ROLE_COLOR[c.role]}`,
             borderRadius: 4,
-            padding: '1px 6px',
+            padding: '0 5px',
           }}
         >
-          <span style={{ textTransform: 'uppercase' }}>
-            {KIND_LABEL[c.kind] ?? c.kind}
-          </span>
-          {c.file ? ` · ${c.file.split('/').pop()}` : ''}
-          {c.capture && c.capture !== 'edited' ? ` · ${c.capture}` : ''}
+          {ROLE_LABEL[c.role]}
         </div>
       )}
 
+      {/* Filename badge — a strip across the bottom border, shown on hover
+          and pinned while this node's file is open in the drawer (fileMatch).
+          Mirrors the construct/role tab badges; hidden for fileless nodes. */}
+      {(hover || fileMatch === true) && c.file ? (
+        <div
+          style={{
+            position: 'absolute',
+            bottom: -13,
+            left: '50%',
+            transform: 'translateX(-50%)',
+            zIndex: 1,
+            fontFamily: theme.fonts.monospace,
+            fontSize: theme.fontSizes[0] * 1.1,
+            letterSpacing: 0.5,
+            lineHeight: '17px',
+            whiteSpace: 'nowrap',
+            // filename stays neutral — the construct color belongs to the
+            // borders and badges, not the file name
+            color: theme.colors.text ?? theme.colors.textSecondary,
+            background: theme.colors.backgroundSecondary ?? theme.colors.background,
+            border: `1px solid ${color}`,
+            borderRadius: 4,
+            padding: '0 5px',
+            cursor: 'pointer',
+          }}
+          onClick={(e) => {
+            // Open the file directly; don't also toggle node selection.
+            e.stopPropagation();
+            SUBSYSTEM_CALLBACKS.onOpenFile?.(c.id);
+          }}
+        >
+          {c.file.split('/').pop()}
+        </div>
+      ) : null}
+
       {/* Purpose is no longer shown as a hover tooltip below the node — it
           lives in the declaration panel and the graphify detail payload. */}
 
@@ -168,7 +238,11 @@ export function SubsystemComponentNode(props: NodeProps<SubsystemGraphNode>) {
         {breakWords(displayName)}
       </div>
 
-      {c.symbol && c.symbol !== displayName && (
+      {/* Hide the identity line when the symbol is just the title without its
+          decoration (`()` or ` {}`) — only show it when it adds information
+          (e.g. the dotted host on methods, or a different code identity). */}
+      {c.symbol &&
+        c.symbol !== displayName.replace(/ ?\{\}$/, '').replace(/\(\)$/, '') && (
         <div
           style={{
             fontSize: theme.fontSizes[0] * 0.82,
@@ -204,7 +278,9 @@ export function SubsystemEdge({
   const path = data?.elkPath ?? '';
   const mechanism = data?.mechanism ?? 'imports';
   const color = MECHANISM_COLOR[mechanism] ?? '#888';
-  const isDashed = mechanism === 'registers-into';
+  // Dash style comes from the mechanism table (dashed = inverted-control or
+  // observational relationships: hierarchy, registration, watches).
+  const isDashed = MECHANISM_STYLE[mechanism] === 'dashed';
   const dimmed = data?.dimmed === true;
   const opacity = dimmed ? 0.15 : 1;
 

package/src/subsystem/tokenizeComponent.ts

@@ -50,7 +50,7 @@ export async function tokenizeComponent(
   if (component.tokens) return component.tokens;
 
   // External kind — not valid TypeScript, bypass Prettier.
-  const kind = component.detail?.kind ?? component.kind;
+  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, "\\'");