@principal-ai/subsystems-react 0.37.0 → 0.37.2

package/src/subsystem/SubsystemComponentGraph.tsx

@@ -70,12 +70,13 @@ import type { DeclarationSymbolRef, SymbolInspection } from './symbolRefs';
 import { FileDrawer, FILE_DRAWER_HEIGHT_MS } from './FileDrawer';
 import { buildRepoGroups, repoAvatarUrl, type RepoGroup } from './paths';
 import { WalkthroughsPanel, WALKTHROUGH_PLAY_PAUSE_MS } from './WalkthroughsPanel';
-
-/** Cap screen-space edge labels to this fraction of the edge's on-screen length. */
-const EDGE_LABEL_MAX_EDGE_FRACTION = 0.55;
-/** Rough monospace width at fontSize 10 + horizontal padding/border. */
-const EDGE_LABEL_CHAR_PX = 6.2;
-const EDGE_LABEL_PAD_PX = 18;
+import {
+  EDGE_LABEL_WIDTH,
+  EDGE_LABEL_HEIGHT,
+  EDGE_LABEL_FONT_SIZE,
+  EDGE_LABEL_CLOUD_PATH,
+  EDGE_LABEL_CLOUD_EXTRA_TOP,
+} from '../utils/edgeLabel';
 
 /** Context passed to `renderWalkthroughViewer` when a flow/step is focused. */
 export interface WalkthroughViewerContext {
@@ -2036,14 +2037,6 @@ function Inner({ components, relations, walkthroughs, initialWalkthroughId, onRe
             const text = lbl.stepNos?.length
               ? `${lbl.stepNos.map((n) => `${n}:`).join(' ')} ${lbl.mechanism}`
               : lbl.mechanism;
-            // Labels stay readable at full size until they'd exceed a share of
-            // the edge's screen length, then shrink with zoom.
-            const estWidth = text.length * EDGE_LABEL_CHAR_PX + EDGE_LABEL_PAD_PX;
-            const screenEdgeLen = lbl.pathLength * viewport.zoom;
-            const scale =
-              lbl.pathLength > 0 && estWidth > 0
-                ? Math.min(1, (screenEdgeLen * EDGE_LABEL_MAX_EDGE_FRACTION) / estWidth)
-                : 1;
             return (
               <div
                 key={lbl.id}
@@ -2057,29 +2050,81 @@ function Inner({ components, relations, walkthroughs, initialWalkthroughId, onRe
                 position: 'absolute',
                 left: screenX,
                 top: screenY,
-                // Center on the flow-space midpoint. Labels live in screen
-                // space (fixed size when zoomed out), so top-left anchoring
-                // would drift them right/down of the edge as zoom drops.
-                transform: `translate(-50%, -50%) scale(${scale})`,
+                // Center on the flow-space midpoint, and scale with the graph
+                // (flow-space size): labels shrink as you zoom out instead of
+                // staying fixed-screen-size and dominating the smaller graph.
+                transform: `translate(-50%, -50%) scale(${viewport.zoom})`,
                 transformOrigin: 'center center',
                 display: 'flex',
                 alignItems: 'center',
-                fontSize: 10,
-                lineHeight: 1,
-                fontFamily: theme.fonts.monospace,
-                fontWeight: 500,
-                color,
-                background: 'rgba(21,21,21,0.9)',
-                border: verifiable ? `0.5px solid ${color}` : `1px dashed ${color}`,
-                borderRadius: verifiable ? 4 : '10px 14px 12px 16px / 14px 10px 16px 12px',
-                padding: '3px 8px',
+                justifyContent: 'center',
+                width: EDGE_LABEL_WIDTH,
+                height: EDGE_LABEL_HEIGHT,
+                boxSizing: 'border-box',
+                padding: '7px 8px',
                 cursor: 'pointer',
                 pointerEvents: 'auto',
                 opacity: lbl.dimmed ? 0.15 : 1,
-                whiteSpace: 'nowrap',
               }}
             >
-              {text}
+              {/* Background layer. Opaque theme surface (matches the node fill)
+                  so the edge line behind is hidden. Verifiable mechanisms get a
+                  crisp rounded box; soft / ambiguous ones (uses, feeds,
+                  watches …) get a real lobed cloud silhouette — ambiguous, not
+                  a dashed proposal (or a pill, which border-radius can only
+                  ever make). */}
+              {verifiable ? (
+                <span
+                  aria-hidden
+                  style={{
+                    position: 'absolute',
+                    inset: 0,
+                    borderRadius: 4,
+                    border: `0.5px solid ${color}`,
+                    background:
+                      theme.colors.backgroundSecondary ?? theme.colors.background,
+                    pointerEvents: 'none',
+                  }}
+                />
+              ) : (
+                <svg
+                  aria-hidden
+                  width={EDGE_LABEL_WIDTH}
+                  height={EDGE_LABEL_HEIGHT + EDGE_LABEL_CLOUD_EXTRA_TOP}
+                  viewBox={`0 0 ${EDGE_LABEL_WIDTH} ${EDGE_LABEL_HEIGHT + EDGE_LABEL_CLOUD_EXTRA_TOP}`}
+                  style={{
+                    position: 'absolute',
+                    left: 0,
+                    top: -EDGE_LABEL_CLOUD_EXTRA_TOP,
+                    pointerEvents: 'none',
+                  }}
+                >
+                  <path
+                    d={EDGE_LABEL_CLOUD_PATH}
+                    fill={theme.colors.backgroundSecondary ?? theme.colors.background}
+                    stroke={hexWithAlpha(color, 0.75)}
+                    strokeWidth={1.2}
+                    strokeLinejoin="round"
+                  />
+                </svg>
+              )}
+              <span
+                style={{
+                  position: 'relative',
+                  display: 'block',
+                  maxWidth: '100%',
+                  overflow: 'hidden',
+                  textOverflow: 'ellipsis',
+                  whiteSpace: 'nowrap',
+                  fontSize: EDGE_LABEL_FONT_SIZE,
+                  lineHeight: 1,
+                  fontFamily: theme.fonts.monospace,
+                  fontWeight: 500,
+                  color,
+                }}
+              >
+                {text}
+              </span>
             </div>
           );
         })}

package/src/subsystem/SymbolInspectionCard.tsx

@@ -337,7 +337,7 @@ export function SymbolInspectionCard({
         ×
       </button>
 
-      {/* Top: the declaration itself, full-bleed (or status when there's none). */}
+      {/* Top: the declaration itself, full-bleed (or just the name on a miss). */}
       <div
         style={{
           padding: '12px 32px 12px 12px',
@@ -363,20 +363,21 @@ export function SymbolInspectionCard({
         )}
 
         {!error && !hasBody && (
-          <div style={{ display: 'flex', flexDirection: 'column', gap: 2 }}>
-            <span style={{ color: theme.colors.accent ?? theme.colors.secondary, fontWeight: 600 }}>
-              {symbolRef.name}
-            </span>
-            <span style={{ color: muted, fontFamily: theme.fonts.body, fontSize: body }}>
-              {statusText}
-            </span>
-          </div>
+          <span style={{ color: theme.colors.accent ?? theme.colors.secondary, fontWeight: 600 }}>
+            {symbolRef.name}
+          </span>
         )}
       </div>
 
       {/* Meta: where it lives, ambiguity, and the action. */}
       {!error && (
         <div style={{ padding: '10px 12px', display: 'flex', flexDirection: 'column', gap: 8 }}>
+        {!hasBody && (
+          <span style={{ color: muted, fontFamily: theme.fonts.body, fontSize: body }}>
+            {statusText}
+          </span>
+        )}
+
         {node?.sourceFile && (
           <StackedRow label="Source">
             {onOpenFile ? (

package/src/subsystem/model.ts

@@ -18,6 +18,7 @@ import {
   type Node,
 } from '@xyflow/react';
 import { computeElkLayout, calculatePathLength } from '../utils/elkLayout';
+import { EDGE_LABEL_SIDE_PADDING, EDGE_ARROW_INSET } from '../utils/edgeLabel';
 import type { GraphifyComponentDetail } from '../graphify';
 import type { SubsystemDeclarationRef } from './declarationRef';
 import { purlOwnerName, purlRepoKey } from './paths';
@@ -1642,7 +1643,12 @@ export async function buildSubsystemGraph(
         nodeSpacing: 60,
         edgeSpacing: 30,
         edgeNodeSpacing: 60,
-        interLayerSpacing: 120,
+        // With labels on, ELK's CENTER_LAYER strategy applies this spacing on
+        // both sides of the label layer, so it IS the per-side clearance — the
+        // label box itself is reserved separately in elkLayout. A large value
+        // here would be counted twice. Labels off → ordinary layer gap.
+        interLayerSpacing: showEdgeLabels === false ? 120 : EDGE_LABEL_SIDE_PADDING,
+        endpointInset: EDGE_ARROW_INSET,
         preserveNodePositions: false,
         edgeLabels: showEdgeLabels === false ? { enabled: false } : { enabled: true, placement: 'CENTER' },
         groups: layoutGroups.map((g) => ({

package/src/utils/edgeLabel.test.ts

@@ -0,0 +1,23 @@
+/**
+ * Tests for the shared edge-label geometry.
+ *
+ * The overlay and the ELK reservation both import these values, so the
+ * invariants here (fixed box, min edge run covers the box) are what keep
+ * rendered labels consistent and non-overlapping.
+ */
+
+import { describe, test, expect } from 'bun:test';
+import {
+  EDGE_LABEL_WIDTH,
+  EDGE_LABEL_SIDE_PADDING,
+  EDGE_LABEL_EDGE_GAP,
+} from './edgeLabel';
+
+describe('edge-label geometry', () => {
+  test('the labelled-edge gap is the box plus clearance on both sides', () => {
+    expect(EDGE_LABEL_EDGE_GAP).toBe(
+      EDGE_LABEL_WIDTH + EDGE_LABEL_SIDE_PADDING * 2,
+    );
+    expect(EDGE_LABEL_EDGE_GAP).toBeGreaterThan(EDGE_LABEL_WIDTH);
+  });
+});

package/src/utils/edgeLabel.ts

@@ -0,0 +1,95 @@
+/**
+ * Shared geometry for the HTML edge-label overlay and the ELK layout that
+ * reserves room for it.
+ *
+ * The overlay (SubsystemComponentGraph) and the layout (elkLayout) must agree
+ * on one fixed box size, or the space ELK leaves for a label drifts from what
+ * actually renders. Keeping the geometry here lets both import the same values
+ * without a component → util → component import cycle.
+ */
+
+/** Fixed width of every edge label, in flow/screen px. Wide enough for the
+ *  longest mechanism (`registers-into`) plus horizontal padding at the label
+ *  font size. */
+export const EDGE_LABEL_WIDTH = 140;
+
+/** Fixed height of every edge label. Sized to the label font plus padding. */
+export const EDGE_LABEL_HEIGHT = 40;
+
+/** Label font size. Fixed so every label renders at the same text size. */
+export const EDGE_LABEL_FONT_SIZE = 14;
+
+/**
+ * Clear space we want on each side of a label box.
+ *
+ * Passed as ELK's `interLayerSpacing` (`nodeNodeBetweenLayers`). ELK's
+ * `CENTER_LAYER` label strategy inserts a dedicated label layer and applies
+ * that spacing on *both* sides of it, so the resulting gap between the two
+ * nodes an edge connects is:
+ *
+ *     EDGE_LABEL_WIDTH + 2 * EDGE_LABEL_SIDE_PADDING
+ *
+ * i.e. the reserved label box plus this clearance at each end. Setting a big
+ * "min edge length" here double-counts (it is applied twice), which is how the
+ * gap silently ballooned before.
+ */
+export const EDGE_LABEL_SIDE_PADDING = 32;
+
+/** Actual end-to-end gap ELK leaves for a labelled edge (box + both clearances). */
+export const EDGE_LABEL_EDGE_GAP =
+  EDGE_LABEL_WIDTH + EDGE_LABEL_SIDE_PADDING * 2;
+
+/**
+ * How far (in flow px) the target end of an edge stops short of the node
+ * border. ELK ends the path exactly on the border, so the arrowhead tip lands
+ * on the border line; pulling it back this much lets the arrow visually touch
+ * the node without overlapping its border. 0 = flush (old behaviour).
+ */
+export const EDGE_ARROW_INSET = 2;
+
+/**
+ * Build a "cloud" outline that fills a `w × h` box: a flat-ish bottom with
+ * rounded corners and three top lobes (large left, medium middle, small right).
+ * Used as the background silhouette for ambiguous (non-verifiable) edge labels —
+ * a real cloud shape, which `border-radius` cannot express. Control points are
+ * normalized (`0…1`) so the shape scales with the label box.
+ */
+function cloudPath(w: number, h: number): string {
+  const p = (nx: number, ny: number) =>
+    `${(nx * w).toFixed(2)} ${(ny * h).toFixed(2)}`;
+  return [
+    `M ${p(0.043, 0.65)}`,
+    // Bottom-left rounded corner + flat bottom.
+    `C ${p(0.014, 0.8)} ${p(0.05, 0.925)} ${p(0.114, 0.925)}`,
+    `L ${p(0.829, 0.925)}`,
+    // Bottom-right rounded corner up into the right (small) lobe.
+    `C ${p(0.914, 0.925)} ${p(0.986, 0.825)} ${p(0.986, 0.675)}`,
+    `C ${p(0.986, 0.475)} ${p(0.943, 0.325)} ${p(0.879, 0.325)}`,
+    `C ${p(0.829, 0.325)} ${p(0.793, 0.425)} ${p(0.771, 0.525)}`,
+    // Middle lobe.
+    `C ${p(0.736, 0.275)} ${p(0.664, 0.15)} ${p(0.6, 0.2)}`,
+    `C ${p(0.564, 0.225)} ${p(0.536, 0.3)} ${p(0.521, 0.375)}`,
+    // Big left lobe.
+    `C ${p(0.486, 0.1)} ${p(0.4, 0.025)} ${p(0.336, 0.075)}`,
+    `C ${p(0.279, 0.1)} ${p(0.243, 0.225)} ${p(0.221, 0.375)}`,
+    // Down the left side, back to the corner.
+    `C ${p(0.2, 0.5)} ${p(0.143, 0.475)} ${p(0.1, 0.525)}`,
+    `C ${p(0.064, 0.55)} ${p(0.057, 0.6)} ${p(0.043, 0.65)}`,
+    'Z',
+  ].join(' ');
+}
+
+/**
+ * Extra height (flow px) the cloud rises above the label box. The cloud and
+ * its text share the label box, but ambiguous labels draw a taller silhouette
+ * that overhangs upward — so the cloud gets more presence without moving the
+ * text or changing the verifiable labels' box.
+ */
+export const EDGE_LABEL_CLOUD_EXTRA_TOP = 14;
+
+/** Cloud silhouette for ambiguous edge labels, matched to the label box. */
+export const EDGE_LABEL_CLOUD_PATH = cloudPath(
+  EDGE_LABEL_WIDTH,
+  EDGE_LABEL_HEIGHT + EDGE_LABEL_CLOUD_EXTRA_TOP,
+);
+

package/src/utils/elkLayout.ts

@@ -7,6 +7,11 @@
 
 import ELK, { type ElkNode, type ElkExtendedEdge, type LayoutOptions } from 'elkjs/lib/elk.bundled.js';
 import type { Node, Edge } from '@xyflow/react';
+import {
+  EDGE_LABEL_WIDTH,
+  EDGE_LABEL_HEIGHT,
+  EDGE_LABEL_SIDE_PADDING,
+} from './edgeLabel';
 
 /** ELK layout options for different routing styles */
 export type ElkRoutingStyle = 'orthogonal' | 'splines' | 'polyline';
@@ -54,6 +59,13 @@ export interface ElkLayoutOptions {
    */
   interLayerSpacing?: number;
 
+  /**
+   * Pull the target end of each edge back from the node border by this many
+   * flow px, so the arrowhead tip touches the node without sitting on its
+   * border. @default 0
+   */
+  endpointInset?: number;
+
   /**
    * Reserve space along edges for inline labels so they don't overlap nodes
    * or other edges. When enabled ELK places labels inline on the edge with the
@@ -486,6 +498,7 @@ export async function computeElkLayout(
 ): Promise<ElkLayoutResult> {
   const { preserveNodePositions = true, keepSingletonGroups = false } = options;
   const edgeLabels = options.edgeLabels;
+  const endpointInset = options.endpointInset ?? 0;
   const direction = options.direction ?? 'RIGHT';
 
   // Build a map of original node positions BEFORE passing to ELK
@@ -620,13 +633,12 @@ export async function computeElkLayout(
       sources: [sourcePort],
       targets: [targetPort],
     };
-    // Estimated label size so ELK reserves room to render the inline label
-    // without it overlapping nodes or sibling edges.
+    // Reserve the fixed label box so ELK leaves the same room for every label,
+    // regardless of text length. The overlay renders into this exact box.
     if (edgeLabels?.enabled !== false && typeof edge.label === 'string') {
-      const text = edge.label;
-      const labelWidth = Math.max(20, text.length * 7); // ~7px per mono char
-      const labelHeight = 14;
-      elkEdge.labels = [{ text, width: labelWidth, height: labelHeight }];
+      elkEdge.labels = [
+        { text: edge.label, width: EDGE_LABEL_WIDTH, height: EDGE_LABEL_HEIGHT },
+      ];
     }
     return elkEdge;
   });
@@ -647,6 +659,12 @@ export async function computeElkLayout(
     // edge by ~13px) plus a gap before the first child.
     'elk.padding': '[top=64,left=24,bottom=24,right=24]',
     'elk.spacing.nodeNode': '40',
+    // Edges inside a frame host labels too: ELK applies this on both sides of
+    // the reserved label layer, so it is the per-side clearance (same as root).
+    // Labels off falls back to a plain between-layer gap.
+    'elk.layered.spacing.nodeNodeBetweenLayers': String(
+      edgeLabels?.enabled === false ? 40 : EDGE_LABEL_SIDE_PADDING,
+    ),
   };
 
   const plan = planCompoundGroups(groupDefs, elkById.keys(), keepSingletonGroups);
@@ -900,6 +918,23 @@ export async function computeElkLayout(
           allPoints.push(end);
         }
 
+        // Pull the target end back from the node border so the arrowhead tip
+        // touches the node without overlapping its border.
+        if (endpointInset > 0 && allPoints.length >= 2) {
+          const end = allPoints[allPoints.length - 1];
+          const prev = allPoints[allPoints.length - 2];
+          const dx = end.x - prev.x;
+          const dy = end.y - prev.y;
+          const segLen = Math.hypot(dx, dy);
+          if (segLen > endpointInset) {
+            const t = (segLen - endpointInset) / segLen;
+            allPoints[allPoints.length - 1] = {
+              x: prev.x + dx * t,
+              y: prev.y + dy * t,
+            };
+          }
+        }
+
         // Convert to path
         const path =
           options.routingStyle === 'orthogonal'