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

package/src/subsystem/model.test.ts

@@ -2,6 +2,9 @@ import { describe, expect, test } from 'bun:test';
 import {
   convertSubsystemToNodes,
   convertSubsystemToEdges,
+  convertSubsystemToGroups,
+  getSubsystemRegions,
+  processGroupNodeId,
   buildSubsystemGraph,
   deriveNameFromSymbol,
   formatPurl,
@@ -121,6 +124,59 @@ describe('subsystem graph model', () => {
     expect(formatPurl('not-a-purl')).toBe('not-a-purl');
   });
 
+  test('getSubsystemRegions groups by process, skipping process-less nodes', () => {
+    const regions = getSubsystemRegions({
+      components: [
+        { id: 'a', name: 'a', construct: 'function', file: 'a.ts', purl: 'pkg:github/acme/app', process: 'app/host' },
+        { id: 'b', name: 'b', construct: 'function', file: 'b.ts', purl: 'pkg:github/acme/app', process: 'app/host' },
+        { id: 'c', name: 'c', construct: 'function', file: 'c.ts', purl: 'pkg:github/acme/app', process: 'app/renderer' },
+        { id: 'd', name: 'd', construct: 'function', file: 'd.ts', purl: 'pkg:github/acme/app' },
+      ],
+    });
+    expect(regions.map((r) => r.key)).toEqual(['app/host', 'app/renderer']);
+    expect(regions[0]!.memberIds).toEqual(['a', 'b']);
+  });
+
+  test('convertSubsystemToNodes stamps parentId for process members only', () => {
+    const nodes = convertSubsystemToNodes({
+      components: [
+        { id: 'a', name: 'a', construct: 'function', file: 'a.ts', purl: 'pkg:github/acme/app', process: 'app/host' },
+        { id: 'd', name: 'd', construct: 'function', file: 'd.ts', purl: 'pkg:github/acme/app' },
+      ],
+      edges: [],
+    });
+    expect((nodes.find((n) => n.id === 'a') as { parentId?: string }).parentId).toBe(
+      processGroupNodeId('app/host'),
+    );
+    expect((nodes.find((n) => n.id === 'd') as { parentId?: string }).parentId).toBeUndefined();
+  });
+
+  test('convertSubsystemToGroups emits one parent per process', () => {
+    const groups = convertSubsystemToGroups({
+      components: [
+        { id: 'a', name: 'a', construct: 'function', file: 'a.ts', purl: 'pkg:github/acme/app', process: 'app/host' },
+        { id: 'b', name: 'b', construct: 'function', file: 'b.ts', purl: 'pkg:github/acme/app', process: 'app/host' },
+      ],
+    });
+    expect(groups).toHaveLength(1);
+    expect(groups[0]!.id).toBe(processGroupNodeId('app/host'));
+    expect(groups[0]!.type).toBe('subsystem-group');
+  });
+
+  test('buildSubsystemGraph drops singleton process frames (no parentId, no group)', async () => {
+    const { nodes, regions } = await buildSubsystemGraph({
+      components: [
+        { id: 'a', name: 'a', construct: 'function', file: 'a.ts', purl: 'pkg:github/acme/app', process: 'app/host' },
+        { id: 'b', name: 'b', construct: 'function', file: 'b.ts', purl: 'pkg:github/acme/app', process: 'app/host' },
+        { id: 'solo', name: 'solo', construct: 'function', file: 's.ts', purl: 'pkg:github/acme/app', process: 'app/lonely' },
+      ],
+      edges: [{ id: 'e1', from: 'a', to: 'b', mechanism: 'calls' }],
+    });
+    expect(regions.map((r) => r.key)).toEqual(['app/host']);
+    expect((nodes.find((n) => n.id === 'solo') as { parentId?: string }).parentId).toBeUndefined();
+    expect(nodes.find((n) => n.id === processGroupNodeId('app/lonely'))).toBeUndefined();
+  });
+
   test('subsystemGraphLayoutKey ignores declarationRef-only changes', () => {
     const base = { components: comps, edges };
     const withRef = {

package/src/subsystem/model.ts

@@ -17,7 +17,7 @@ import {
   type Edge,
   type Node,
 } from '@xyflow/react';
-import { computeElkLayout } from '../utils/elkLayout';
+import { computeElkLayout, calculatePathLength } from '../utils/elkLayout';
 import type { GraphifyComponentDetail } from '../graphify';
 import type { SubsystemDeclarationRef } from './declarationRef';
 
@@ -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[];
 }
 
 // ---------------------------------------------------------------------------
@@ -258,15 +292,65 @@ export interface SubsystemGraphDocument {
 
 export type SubsystemGraphNodeType = 'subsystem-component' | 'subsystem-group';
 
+/**
+ * One process boundary region — all components sharing a `process` value.
+ * Nodes without a `process` sit outside every boundary (no region).
+ */
+export interface SubsystemProcessRegion {
+  /** The `process` value (e.g. `trail-viewer/host`). */
+  key: string;
+  /** Display label for the boundary frame. */
+  label: string;
+  /** Component ids that are members of this region. */
+  memberIds: string[];
+}
+
+/** React Flow id for a process boundary group node. */
+export function processGroupNodeId(processKey: string): string {
+  return `process:${processKey}`;
+}
+
+/**
+ * Derive boundary regions from a document — one per distinct non-empty
+ * `process` value, in first-appearance order.
+ */
+export function getSubsystemRegions(
+  doc: Pick<SubsystemGraphDocument, 'components'>,
+): SubsystemProcessRegion[] {
+  const byProcess = new Map<string, string[]>();
+  for (const c of doc.components) {
+    const p = c.process?.trim();
+    if (!p) continue;
+    const list = byProcess.get(p) ?? [];
+    list.push(c.id);
+    byProcess.set(p, list);
+  }
+  return [...byProcess.entries()].map(([key, memberIds]) => ({
+    key,
+    label: key,
+    memberIds,
+  }));
+}
+
 export interface SubsystemGraphNodeData extends Record<string, unknown> {
   component: SubsystemComponent;
   /** Set while a file is open in the drawer: true if this node's component
    *  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>;
+export interface SubsystemGroupNodeData extends Record<string, unknown> {
+  region: SubsystemProcessRegion;
+  /** True while the region's members are dimmed by flow focus. */
+  dimmed?: boolean;
+}
+
+export type SubsystemGraphNode =
+  | Node<SubsystemGraphNodeData, 'subsystem-component'>
+  | Node<SubsystemGroupNodeData, 'subsystem-group'>;
 
 export interface SubsystemGraphEdgeData extends Record<string, unknown> {
   mechanism: SubsystemEdgeMechanism;
@@ -277,6 +361,8 @@ export interface SubsystemGraphEdgeData extends Record<string, unknown> {
   /** ELK-computed label midpoint (from the actual edge path, not node centers). */
   labelX?: number;
   labelY?: number;
+  /** Polyline length in flow-space units (for capping screen-space label size). */
+  pathLength?: number;
   /** ELK-computed SVG edge path (overrides React Flow's default path). */
   elkPath?: string;
 }
@@ -358,12 +444,11 @@ export const ROLE_LABEL: Record<SubsystemComponentRole, string> = {
 };
 
 /**
- * Convert a subsystem graph document into React Flow nodes. We render **flat**
- * (no React Flow parent/group nodes) for robustness: package regions are laid
- * out in a grid and each component carries its package + a `pkgBounds`
- * rectangle on its node data so the group wrapper (drawn by the graph
- * component) can frame it. Only components' real positions matter to React
- * Flow; the package boundary is a visual region, not a sub-flow node.
+ * Convert a subsystem graph document into React Flow nodes. Components that
+ * carry a `process` get a `parentId` pointing at their boundary group node
+ * (`process:<process>`); nodes without one stay top-level (outside every
+ * boundary). The initial grid groups by `process ?? purl` so the pre-ELK
+ * positions are already clustered; ELK then refines with compound layout.
  */
 export function convertSubsystemToNodes(
   doc: SubsystemGraphDocument,
@@ -411,9 +496,11 @@ export function convertSubsystemToNodes(
       const cssBorder = 4; // 2px border each side
       const rawWidth = Math.max(cssMinWidth, textWidth + cssPadding + cssBorder);
       const nodeWidth = Math.max(cssMinWidth, Math.min(cap, rawWidth));
+      const processKey = c.process?.trim();
       nodes.push({
         id: c.id,
         type: 'subsystem-component',
+        ...(processKey ? { parentId: processGroupNodeId(processKey) } : {}),
         position: { x: PAD + col * COL_W, y: cursorY + row * ROW_H },
         width: nodeWidth,
         height: 84,
@@ -425,6 +512,24 @@ export function convertSubsystemToNodes(
   return nodes;
 }
 
+/**
+ * Convert boundary regions into React Flow parent (group) nodes. One per
+ * distinct `process` value; member components point at these via `parentId`.
+ * Positions/sizes are placeholders — ELK compound layout overwrites them.
+ */
+export function convertSubsystemToGroups(
+  doc: Pick<SubsystemGraphDocument, 'components'>,
+): SubsystemGraphNode[] {
+  return getSubsystemRegions(doc).map((region) => ({
+    id: processGroupNodeId(region.key),
+    type: 'subsystem-group',
+    position: { x: 0, y: 0 },
+    width: 400,
+    height: 300,
+    data: { region },
+  }));
+}
+
 /**
  * Convert a subsystem graph document into React Flow edges. Edges whose target
  * is an external label (not a component id) point at a synthetic stub so the
@@ -447,7 +552,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.
@@ -486,10 +591,23 @@ export async function buildSubsystemGraph(
 ): Promise<{
   nodes: SubsystemGraphNode[];
   edges: SubsystemGraphEdge[];
+  regions: SubsystemProcessRegion[];
 }> {
   const { maxNodeWidth, showEdgeLabels, measuredWidths, measuredHeights } = opts;
   const nodes = convertSubsystemToNodes(doc, { maxNodeWidth });
   const edges = convertSubsystemToEdges(doc);
+  // Boundary regions: one per multi-member process. Singletons get no frame —
+  // strip the parentId convertSubsystemToNodes stamped so React Flow never
+  // points at a non-existent parent.
+  const regions = getSubsystemRegions(doc).filter((r) => r.memberIds.length >= 2);
+  const regionKeys = new Set(regions.map((r) => r.key));
+  for (const n of nodes) {
+    if (n.type !== 'subsystem-component') continue;
+    const proc = (n.data as SubsystemGraphNodeData).component?.process?.trim();
+    if (proc && !regionKeys.has(proc)) {
+      delete (n as { parentId?: string }).parentId;
+    }
+  }
 
   // External edge targets that aren't real components → create stub nodes so
   // cross-package edges have something to land on.
@@ -538,10 +656,12 @@ export async function buildSubsystemGraph(
     }
   }
 
-  // ELK auto-layout: position nodes (layered, minimized crossings).
+  // ELK auto-layout: position nodes (layered, minimized crossings) with
+  // process partitions as compound parents so boundaries shape the layout.
   let placedNodes = nodes;
   let labelPositions = new Map<string, { x: number; y: number }>();
   let elkPathStrings = new Map<string, string>();
+  let elkPathPoints = new Map<string, { x: number; y: number }[]>();
   if (nodes.length > 0) {
     try {
       const result = await computeElkLayout(nodes, edges, {
@@ -553,10 +673,29 @@ export async function buildSubsystemGraph(
         interLayerSpacing: 120,
         preserveNodePositions: false,
         edgeLabels: showEdgeLabels === false ? { enabled: false } : { enabled: true, placement: 'CENTER' },
+        groups: regions.map((r) => ({
+          id: processGroupNodeId(r.key),
+          memberIds: r.memberIds,
+        })),
+      });
+      const groupNodes: SubsystemGraphNode[] = regions.flatMap((region) => {
+        const bounds = result.groupBounds.get(processGroupNodeId(region.key));
+        if (!bounds) return [];
+        const group: SubsystemGraphNode = {
+          id: processGroupNodeId(region.key),
+          type: 'subsystem-group',
+          position: { x: bounds.x, y: bounds.y },
+          width: Math.max(200, bounds.width),
+          height: Math.max(160, bounds.height),
+          data: { region },
+        };
+        return [group];
       });
-      placedNodes = result.nodes as SubsystemGraphNode[];
+      // Parents first — React Flow resolves children via parentId.
+      placedNodes = [...groupNodes, ...(result.nodes as SubsystemGraphNode[])];
       labelPositions = result.edgeLabelPositions;
       elkPathStrings = result.edgePaths;
+      elkPathPoints = result.edgePathPoints;
     } catch (err) {
       // Fall back to the (unpositioned) grid if ELK is unavailable.
       console.warn('[subsystem-graph] ELK layout failed, using manual positions:', err);
@@ -577,7 +716,12 @@ export async function buildSubsystemGraph(
       const d = (e as SubsystemGraphEdge).data as SubsystemGraphEdgeData;
       d.elkPath = elkP;
     }
+    const pts = elkPathPoints.get(e.id);
+    if (pts && pts.length > 1) {
+      const d = (e as SubsystemGraphEdge).data as SubsystemGraphEdgeData;
+      d.pathLength = calculatePathLength(pts);
+    }
   }
 
-  return { nodes: placedNodes, edges };
+  return { nodes: placedNodes, edges, regions };
 }

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

@@ -11,6 +11,7 @@ import { useState } from 'react';
 import {
   Handle,
   Position,
+  type Node,
   type NodeProps,
   type EdgeProps,
 } from '@xyflow/react';
@@ -21,7 +22,9 @@ import {
   ROLE_COLOR,
   ROLE_LABEL,
   deriveNameFromSymbol,
-  type SubsystemGraphNode,
+  packageColor,
+  type SubsystemGraphNodeData,
+  type SubsystemGroupNodeData,
   type SubsystemGraphEdge,
 } from './model';
 import { constructColorsFromPierreTheme } from '../pierre/constructColors';
@@ -70,7 +73,7 @@ export interface SubsystemGraphCallbacks {
 /** Root callbacks carried through node data (injected by the graph component). */
 export const SUBSYSTEM_CALLBACKS: SubsystemGraphCallbacks = {};
 
-export function SubsystemComponentNode(props: NodeProps<SubsystemGraphNode>) {
+export function SubsystemComponentNode(props: NodeProps<Node<SubsystemGraphNodeData, 'subsystem-component'>>) {
   const { theme, mode } = useTheme();
   const { data, selected, width: nodeWidth, height: nodeHeight } = props;
   const c = data.component;
@@ -126,7 +129,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 +270,117 @@ export function SubsystemComponentNode(props: NodeProps<SubsystemGraphNode>) {
   );
 }
 
+/**
+ * Process boundary frame — a React Flow parent node. Members render inside
+ * via `parentId`; this draws the labeled container only (no handles, no
+ * selection). The border color derives deterministically from the process key
+ * so each deployment unit reads as its own region.
+ */
+export function SubsystemGroupNode(props: NodeProps<Node<SubsystemGroupNodeData, 'subsystem-group'>>) {
+  const { theme } = useTheme();
+  const { data, width, height, selected } = props as unknown as {
+    data: SubsystemGroupNodeData;
+    width?: number;
+    height?: number;
+    selected?: boolean;
+  };
+  const region = data.region;
+  const color = packageColor(region?.key ?? 'process');
+  const dimmed = data.dimmed === true;
+  const hidden = (data as { hidden?: boolean }).hidden === true;
+
+  if (!region) return null;
+
+  return (
+    <div
+      style={{
+        position: 'relative',
+        width: width ?? 400,
+        height: height ?? 300,
+        boxSizing: 'border-box',
+        borderRadius: 12,
+        border: `2px ${selected ? 'solid' : 'dashed'} ${color}`,
+        background: `${color}14`,
+        opacity: hidden ? 0 : dimmed ? 0.35 : 1,
+        transition: 'opacity 150ms ease',
+        pointerEvents: 'none',
+      }}
+    >
+      <div
+        style={{
+          position: 'absolute',
+          top: -13,
+          left: 12,
+          fontFamily: theme.fonts.monospace,
+          fontSize: theme.fontSizes[0],
+          fontWeight: 700,
+          letterSpacing: 0.6,
+          color,
+          background: theme.colors.backgroundSecondary ?? theme.colors.background,
+          border: `1px solid ${color}`,
+          borderRadius: 4,
+          padding: '1px 7px',
+          whiteSpace: 'nowrap',
+        }}
+      >
+        {`process: ${region.label}`}
+      </div>
+    </div>
+  );
+}
+
+/** `#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 +396,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 +418,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' }}
       />