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

package/src/subsystem/model.ts

@@ -177,6 +177,38 @@ export interface SubsystemComponentEdge {
   refs?: string[];
 }
 
+/**
+ * A single site on an existing edge — the exact `file:line` where that edge's
+ * seam manifests for a given flow. The edge stays the abstract contract
+ * (`from`, `to`, `mechanism`); a throughline step picks the concrete
+ * manifestation. One edge can appear in many steps.
+ */
+export interface SubsystemThroughlineStep {
+  /** Id of the existing edge this hop traverses. */
+  edgeId: string;
+  /** Repo-root-relative path of the file where the edge fires. */
+  file: string;
+  /** 1-based line of the site within `file`. */
+  line: number;
+  /**
+   * Frame name for this hop — the function/method/symbol on the stack at
+   * this site. Optional so existing throughlines keep working; when set the
+   * flows list shows it instead of mechanism + filename.
+   */
+  symbol?: string;
+}
+
+/**
+ * An ordered execution story over a graph's edges — each step references an
+ * existing edge and the exact site where that relationship fires for a flow;
+ * ordering is the array. One throughline per flow (save flow, load flow, …).
+ */
+export interface SubsystemThroughline {
+  id: string;
+  title: string;
+  steps: SubsystemThroughlineStep[];
+}
+
 /**
  * Derive a consistent display `name` from a code `symbol` + construct.
  *
@@ -250,6 +282,8 @@ export function formatPurl(purl: string): string {
 export interface SubsystemGraphDocument {
   components: SubsystemComponent[];
   edges: SubsystemComponentEdge[];
+  /** Ordered execution stories over the graph's edges (one per flow). */
+  throughlines?: SubsystemThroughline[];
 }
 
 // ---------------------------------------------------------------------------
@@ -264,6 +298,8 @@ export interface SubsystemGraphNodeData extends Record<string, unknown> {
    *  lives in that file (spotlighted), false otherwise (dimmed). Absent when
    *  no file is open — render neutrally. */
   fileMatch?: boolean;
+  /** True while this node is on an opened-but-unselected flow. */
+  dimmed?: boolean;
 }
 
 export type SubsystemGraphNode = Node<SubsystemGraphNodeData, SubsystemGraphNodeType>;
@@ -447,7 +483,7 @@ export function convertSubsystemToEdges(doc: SubsystemGraphDocument): SubsystemG
       target: targetId,
       data: { mechanism: e.mechanism, refs: e.refs },
       type: 'subsystem-edge',
-      markerEnd: { type: MarkerType.ArrowClosed, color, width: 16, height: 16 },
+      markerEnd: { type: MarkerType.ArrowClosed, color, width: 32, height: 32 },
       style: { color, stroke: color, strokeDasharray: style === 'dashed' ? '6 4' : undefined },
       // `label` feeds ELK's label-space reservation only; the visible label is
       // rendered by the custom SubsystemEdge as an HTML overlay.

package/src/subsystem/nodes.test.ts

@@ -0,0 +1,56 @@
+import { describe, expect, test } from 'bun:test';
+import { EDGE_DIM_ALPHA, fileMatchForNode, flowElementVisibility, hexWithAlpha } from './nodes';
+
+describe('hexWithAlpha', () => {
+  test('appends a two-digit alpha to #rrggbb', () => {
+    expect(hexWithAlpha('#4ec9b0', 1)).toBe('#4ec9b0ff');
+    expect(hexWithAlpha('#4ec9b0', EDGE_DIM_ALPHA)).toBe('#4ec9b026');
+  });
+
+  test('expands #rgb', () => {
+    expect(hexWithAlpha('#abc', 1)).toBe('#aabbccff');
+  });
+
+  test('leaves non-hex values alone', () => {
+    expect(hexWithAlpha('teal', 0.15)).toBe('teal');
+  });
+});
+
+describe('fileMatchForNode', () => {
+  test('no open file → neutral', () => {
+    expect(fileMatchForNode('src/a.ts', null, false)).toBeUndefined();
+  });
+
+  test('open file spotlights matches and dims others', () => {
+    expect(fileMatchForNode('src/a.ts', 'src/a.ts', false)).toBe(true);
+    expect(fileMatchForNode('src/b.ts', 'src/a.ts', false)).toBe(false);
+  });
+
+  test('focused-edge endpoint is not dimmed when it lives in another file', () => {
+    expect(fileMatchForNode('src/target.ts', 'src/source.ts', true)).toBeUndefined();
+    expect(fileMatchForNode('src/source.ts', 'src/source.ts', true)).toBe(true);
+  });
+});
+
+describe('flowElementVisibility', () => {
+  test('nothing open or selected → everything full', () => {
+    expect(flowElementVisibility({ inOpened: false, inSelected: false, anyOpened: false, anySelected: false }))
+      .toEqual({ hidden: false, dimmed: false });
+  });
+
+  test('opened, nothing selected → opened members full, rest hidden', () => {
+    expect(flowElementVisibility({ inOpened: true, inSelected: false, anyOpened: true, anySelected: false }))
+      .toEqual({ hidden: false, dimmed: false });
+    expect(flowElementVisibility({ inOpened: false, inSelected: false, anyOpened: true, anySelected: false }))
+      .toEqual({ hidden: true, dimmed: false });
+  });
+
+  test('selected flow or step full; other opened members dimmed; rest hidden', () => {
+    expect(flowElementVisibility({ inOpened: true, inSelected: true, anyOpened: true, anySelected: true }))
+      .toEqual({ hidden: false, dimmed: false });
+    expect(flowElementVisibility({ inOpened: true, inSelected: false, anyOpened: true, anySelected: true }))
+      .toEqual({ hidden: false, dimmed: true });
+    expect(flowElementVisibility({ inOpened: false, inSelected: false, anyOpened: true, anySelected: true }))
+      .toEqual({ hidden: true, dimmed: false });
+  });
+});

package/src/subsystem/nodes.tsx

@@ -126,7 +126,7 @@ export function SubsystemComponentNode(props: NodeProps<SubsystemGraphNode>) {
         boxShadow: fileMatch
           ? `0 1px 4px rgba(0,0,0,0.25), 0 0 12px ${theme.colors.primary}55`
           : '0 1px 4px rgba(0,0,0,0.25)',
-        opacity: fileMatch === false ? 0.18 : 1,
+        opacity: fileMatch === false || data.dimmed === true ? 0.18 : 1,
         transition: 'opacity 150ms ease',
         cursor: 'pointer',
         fontFamily: theme.fonts.body,
@@ -267,6 +267,58 @@ export function SubsystemComponentNode(props: NodeProps<SubsystemGraphNode>) {
   );
 }
 
+/** `#rrggbb` + alpha → `#rrggbbaa`. Used to dim a stroke/marker by color so
+ *  each opacity gets its own SVG marker id — path `opacity` leaks across every
+ *  edge that shares a `url(#marker)` (the focused edge's arrowhead dims). */
+export function hexWithAlpha(hex: string, alpha: number): string {
+  const raw = hex.replace('#', '');
+  const full = raw.length === 3 ? [...raw].map((c) => c + c).join('') : raw;
+  if (!/^[0-9a-fA-F]{6}$/.test(full)) return hex;
+  const a = Math.round(Math.min(1, Math.max(0, alpha)) * 255)
+    .toString(16)
+    .padStart(2, '0');
+  return `#${full}${a}`;
+}
+
+/**
+ * File-open spotlight flag for a node. `true` = lives in the open file,
+ * `false` = dim, `undefined` = render neutrally.
+ *
+ * Focused-edge endpoints stay neutral when they don't live in the open file
+ * (the target of a focused edge must not dim with the rest).
+ */
+export function fileMatchForNode(
+  nodeFile: string | undefined,
+  openFile: string | null,
+  isFocusEndpoint: boolean,
+): boolean | undefined {
+  if (!openFile) return undefined;
+  if (nodeFile === openFile) return true;
+  if (isFocusEndpoint) return undefined;
+  return false;
+}
+
+/**
+ * Hide / dim a node or edge while flows are open.
+ * - not in any opened flow → hidden
+ * - in an opened flow, but not the selected flow/step → dimmed
+ * - in the selected flow or step (or opened with nothing selected) → full
+ */
+export function flowElementVisibility(opts: {
+  inOpened: boolean;
+  inSelected: boolean;
+  anyOpened: boolean;
+  anySelected: boolean;
+}): { hidden: boolean; dimmed: boolean } {
+  const { inOpened, inSelected, anyOpened, anySelected } = opts;
+  if (!anyOpened && !anySelected) return { hidden: false, dimmed: false };
+  if (!inOpened && !inSelected) return { hidden: true, dimmed: false };
+  if (anySelected && !inSelected) return { hidden: false, dimmed: true };
+  return { hidden: false, dimmed: false };
+}
+
+export const EDGE_DIM_ALPHA = 0.15;
+
 /** Subsystem edge — SVG path only. The mechanism label is rendered as an
  *  absolutely-positioned HTML overlay OUTSIDE the ReactFlow tree (by the
  *  parent Inner component) so it sits above the pane and receives pointer
@@ -282,7 +334,10 @@ export function SubsystemEdge({
   // observational relationships: hierarchy, registration, watches).
   const isDashed = MECHANISM_STYLE[mechanism] === 'dashed';
   const dimmed = data?.dimmed === true;
-  const opacity = dimmed ? 0.15 : 1;
+  // Dim the stroke by color, never via path `opacity`. SVG markers are shared
+  // by id; opacity on the referencing path paints every arrowhead that uses
+  // the same marker — including the focused edge's target.
+  const stroke = dimmed ? hexWithAlpha(color, EDGE_DIM_ALPHA) : color;
 
   return (
     <>
@@ -301,10 +356,9 @@ export function SubsystemEdge({
       <path
         d={path}
         fill="none"
-        stroke={color}
+        stroke={stroke}
         strokeWidth={1.5}
         strokeDasharray={isDashed ? '6 4' : undefined}
-        opacity={opacity}
         markerEnd={markerEnd}
         style={{ pointerEvents: 'none' }}
       />

package/src/utils/elkLayout.ts

@@ -529,9 +529,10 @@ export async function computeElkLayout(
         // and apply the same coordinate offset.
         if (edge.labels && edge.labels.length > 0) {
           const elkLabel = edge.labels[0];
-          // Raw ELK label position — no conversion.
-          let lx = elkLabel.x ?? 0;
-          let ly = elkLabel.y ?? 0;
+          // ELK reports the label's top-left; convert to center so screen-space
+          // overlays can anchor with translate(-50%, -50%) at any zoom.
+          let lx = (elkLabel.x ?? 0) + (elkLabel.width ?? 0) / 2;
+          let ly = (elkLabel.y ?? 0) + (elkLabel.height ?? 0) / 2;
           if (preserveNodePositions && sourceOriginal && sourceElk && targetOriginal && targetElk) {
             const sourceOffset = {
               x: sourceOriginal.x - sourceElk.x,