@principal-ai/subsystems-react 0.53.1 → 0.53.3

package/src/subsystem/C4NodeCard.test.ts

@@ -11,6 +11,8 @@ import {
   NODE_H,
   nodeSize,
   COMPONENT_SIZE,
+  COMPONENT_W,
+  COMPONENT_ASPECT,
 } from './C4NodeCard';
 import type { C4Element, C4Container } from './c4';
 
@@ -190,6 +192,19 @@ describe('nodeShape — kind without relying on colour or dash', () => {
     expect(s.radius).toBeGreaterThanOrEqual(NODE_H / 2);
   });
 
+  test('a component centres its text, a container does not', () => {
+    // Alignment is the cheapest level cue there is: it needs no comparison
+    // against anything else, so it survives a crop or a narrow viewport where
+    // the aspect ratio stops being readable.
+    expect(nodeShape(node({ kind: 'component' })).align).toBe('center');
+    expect(nodeShape(node()).align).toBe('left');
+  });
+
+  test('a person centres its text too, but for its own reason', () => {
+    // Not a level cue — a pill has no straight edge for text to sit against.
+    expect(nodeShape(node({ kind: 'person' })).align).toBe('center');
+  });
+
   test('shape does not depend on confirmation state', () => {
     expect(nodeShape(node({ state: 'proposed' })).kind).toBe(
       nodeShape(node({ state: 'accepted' })).kind,
@@ -250,10 +265,19 @@ describe('nodeMissing', () => {
   });
 });
 
-describe('nodeSize — a component is a proper square', () => {
-  test('a component has equal width and height', () => {
+describe('nodeSize — a component reads as a square', () => {
+  test('a component is wider than it is tall, by the optical correction', () => {
+    // Equal sides get perceived as tall, so the box is built 8:7 to land on the
+    // square we actually want. Pinned both ways: the ratio the layout gets, and
+    // a ceiling on how far the correction may go — the upper bound is there to
+    // stop the box drifting toward the container's 5:3, which would cost the
+    // level signal this aspect exists to carry.
     const s = nodeSize(node({ kind: 'component' }));
-    expect(s.width).toBe(s.height);
+    expect(s.width).toBeGreaterThan(s.height);
+    expect(s.width / s.height).toBeCloseTo(COMPONENT_ASPECT, 2);
+    expect(COMPONENT_ASPECT).toBeGreaterThan(1);
+    expect(COMPONENT_ASPECT).toBeLessThanOrEqual(1.25);
+    expect(COMPONENT_ASPECT).toBeLessThan(NODE_W / NODE_H);
   });
 
   test('a container is wider than it is tall', () => {
@@ -268,9 +292,19 @@ describe('nodeSize — a component is a proper square', () => {
     expect(c.height).toBeLessThan(k.height);
   });
 
-  test('the square still fits its three lines of text', () => {
+  test('the two levels are not the same shape', () => {
+    // The reason a separate constant exists at all: a component is the
+    // square-ish member of the set, not a miniature container.
+    const c = nodeSize(node({ kind: 'component' }));
+    const k = nodeSize(node());
+    expect(c.width / c.height).toBeLessThan(1.2);
+    expect(k.width / k.height).toBeGreaterThan(1.5);
+  });
+
+  test('the box still fits its three lines of text', () => {
     // tag + 2-line label slot + subtitle + 10px padding x2. Without this the
-    // square clips its own subtitle.
+    // component clips its own subtitle. The optical correction is applied to
+    // the width only, so this still holds at 140 tall.
     const s = nodeSize(node({ kind: 'component' }));
     const content = 16 + 40 + 16 + 20;
     expect(s.height).toBeGreaterThanOrEqual(content);
@@ -289,9 +323,14 @@ describe('card metrics', () => {
     expect(NODE_H).toBe(150);
   });
 
-  test('COMPONENT_SIZE is a square, not just a smaller rectangle', () => {
-    expect(COMPONENT_SIZE).toBe(nodeSize(node({ kind: 'component' })).width);
-    expect(COMPONENT_SIZE).toBe(nodeSize(node({ kind: 'component' })).height);
+  test('COMPONENT_SIZE is the short side, not the width', () => {
+    // Kept for callers that size off a single number. It is the height; the
+    // width the graph lays out against is COMPONENT_W, and collapsing the two
+    // back into one number would delete the optical correction.
+    const s = nodeSize(node({ kind: 'component' }));
+    expect(COMPONENT_SIZE).toBe(s.height);
+    expect(COMPONENT_SIZE).not.toBe(s.width);
+    expect(COMPONENT_W).toBe(s.width);
   });
 
   test('is near-square, not a wide strip', () => {

package/src/subsystem/C4NodeCard.tsx

@@ -12,6 +12,7 @@
  * wants it: technology on the top row, description under the label.
  */
 
+import { useLayoutEffect, useRef } from 'react';
 import { useTheme } from '@principal-ade/industry-theme';
 import { AppWindow, Component, Database, Maximize2 } from 'lucide-react';
 import type { LucideIcon } from 'lucide-react';
@@ -27,20 +28,45 @@ export const NODE_W = 250;
 export const NODE_H = 150;
 
 /**
- * A component is a proper square — equal sides, and visibly smaller than the
- * container it sits inside. Square-vs-rectangle is the clearest signal that
- * these are different C4 levels, and it survives grayscale and colour-blind
- * reading where a border-weight difference alone does not.
+ * A component has to *read* as a square, and equal sides do not manage that.
+ *
+ * A literally square box is perceived as tall: the eye measures it against the
+ * upright frame and the surrounding boxes, not against an abstract 1:1, so it
+ * lands looking narrower than it is. The correction is to make the real thing
+ * wider than it is tall, which is what this is for.
+ *
+ * 8:7 is further than the textbook 5%, and deliberately: the card's height is a
+ * `minHeight`, so a long description grows the drawn box past the height
+ * reserved here (see the probe below). 160 buys the square reading against a
+ * *rendered* height that runs past 140, not just against the nominal one.
+ *
+ * The level signal survives it: 8:7 is still unmistakably the square member of
+ * the set against the container's 5:3, and still beats a border-weight
+ * difference alone under grayscale and colour-blind reading.
+ */
+export const COMPONENT_ASPECT = 8 / 7;
+
+/** Short side of a component card — the height, and a hard ceiling on the drawn box. */
+export const COMPONENT_H = 140;
+
+/** Long side — the optically corrected one. 160, derived so the ratio is the constant. */
+export const COMPONENT_W = Math.round(COMPONENT_H * COMPONENT_ASPECT);
+
+/**
+ * Nominal edge of a component card, for callers that sized a box off a single
+ * number. It is the *short* side; the width the graph lays out against is
+ * `COMPONENT_W`, not this.
  */
-export const COMPONENT_SIZE = 140;
+export const COMPONENT_SIZE = COMPONENT_H;
 
 /**
- * Per-level box size. The graph lays out against these, so a square component
- * and a rectangular container do not collide at a shared nominal width.
+ * Per-level box size. The graph lays out against these, so a near-square
+ * component and a rectangular container do not collide at a shared nominal
+ * width.
  */
 export function nodeSize(node: C4Element): { width: number; height: number } {
   return node.kind === 'component'
-    ? { width: COMPONENT_SIZE, height: COMPONENT_SIZE }
+    ? { width: COMPONENT_W, height: COMPONENT_H }
     : { width: NODE_W, height: NODE_H };
 }
 
@@ -186,6 +212,13 @@ export interface NodeShape {
   kind: C4ShapeKind;
   /** Corner radius, for the shapes that use one. */
   radius: number;
+  /**
+   * Horizontal text alignment. This is a level cue, not a typographic
+   * preference: a column of left-aligned containers beside a set of centred
+   * ones reads as two kinds without comparing box sizes, and unlike the aspect
+   * ratio it survives a crop or a narrow viewport.
+   */
+  align: 'left' | 'center';
 }
 
 /**
@@ -195,24 +228,30 @@ export interface NodeShape {
  * The convention:
  *
  *   container        wide rectangle, slight radius — a runtime boundary
- *   component        square — a part inside one (see `nodeSize`)
- *   external system  wide rectangle, no radius    — someone else's system
- *   person           pill                          — not a box at all
+ *   component        square, text centred       — a part inside one
+ *   external system  wide rectangle, no radius   — someone else's system
+ *   person           pill, text centred          — not a box at all
+ *
+ * `square` here is a corner treatment, not a claim about the dimensions: a
+ * component's box is optically 8:7 (see `COMPONENT_ASPECT`) and still reads as
+ * this shape.
  *
  * A container keeps a slight radius; an external system is drawn with none, so
  * the two are distinguishable by corner treatment as well as by the kind icon
- * and frame position. The border dash stays spent on proposed-vs-accepted.
+ * and frame position. Alignment is the third, cheapest cue — it needs no
+ * comparison against anything. The border dash stays spent on
+ * proposed-vs-accepted.
  */
 export function nodeShape(node: C4Element): NodeShape {
   switch (node.kind) {
     case 'person':
-      return { kind: 'pill', radius: NODE_H / 2 };
+      return { kind: 'pill', radius: NODE_H / 2, align: 'center' };
     case 'external-system':
-      return { kind: 'rect', radius: 0 };
+      return { kind: 'rect', radius: 0, align: 'left' };
     case 'component':
-      return { kind: 'square', radius: 6 };
+      return { kind: 'square', radius: 6, align: 'center' };
     case 'container':
-      return { kind: 'rect', radius: 4 };
+      return { kind: 'rect', radius: 4, align: 'left' };
   }
 }
 
@@ -280,12 +319,37 @@ export function C4NodeCard({ node, selected = false, handles, onClick, component
   const subtitle = nodeSubtitle(node);
 
   const size = nodeSize(node);
-  // A pill (a person) has no straight left edge, so left-aligned text reads as
-  // spilling out of the oval. Centre the text and inset it from the curve.
-  const centered = shape.kind === 'pill';
+  const centered = shape.align === 'center';
+  // The pill's inset is a separate concern from alignment, and a centred
+  // component must not inherit it: 30px of each side would leave a 160-wide box
+  // 100px of text, which wraps the description into exactly the extra lines
+  // that grow the box past the height the layout reserved.
+  const pillInset = shape.kind === 'pill';
+
+  // TEMPORARY diagnostic — remove. The card's height is `minHeight`, so the box
+  // the browser lays out can exceed the nominal size the layout reserved, and
+  // nothing in the type system shows that: `nodeSize` and the drawn box are two
+  // different numbers. `offsetWidth/Height` are the border box, so this reports
+  // what was actually drawn. Logs on change only, so a reflow that does not
+  // resize the card stays quiet.
+  const probeRef = useRef<HTMLDivElement | null>(null);
+  const probeSeen = useRef('');
+  useLayoutEffect(() => {
+    const el = probeRef.current;
+    if (!el || typeof ResizeObserver === 'undefined') return;
+    const ro = new ResizeObserver(() => {
+      const line = `${el.offsetWidth}x${el.offsetHeight} (nominal ${size.width}x${size.height})`;
+      if (line === probeSeen.current) return;
+      probeSeen.current = line;
+      console.log(`[c4-card] ${node.kind} ${node.id} ${line}`);
+    });
+    ro.observe(el);
+    return () => ro.disconnect();
+  }, [node.kind, node.id, size.width, size.height]);
 
   return (
     <div
+      ref={probeRef}
       onClick={onClick}
       style={{
         position: 'relative',
@@ -300,7 +364,7 @@ export function C4NodeCard({ node, selected = false, handles, onClick, component
         // height on every card. In a graph grid that makes the row unscannable.
         justifyContent: 'flex-start',
         gap: 3,
-        padding: centered ? '10px 30px' : '10px 12px',
+        padding: pillInset ? '10px 30px' : '10px 12px',
         borderRadius: shape.radius,
         background: theme.colors.backgroundSecondary ?? theme.colors.background,
         border: `${style.width}px ${style.dash} ${style.color}`,

package/src/subsystem/IssueList.tsx

@@ -14,6 +14,7 @@
 import { useEffect, useRef, useState } from 'react';
 import type { LucideIcon } from 'lucide-react';
 import {
+  AppWindow,
   ChevronDown,
   ChevronRight,
   CircleCheck,
@@ -32,7 +33,6 @@ import {
   Network,
   Route,
   Search,
-  Server,
   Shapes,
   Sigma,
   Split,
@@ -82,7 +82,7 @@ export const SUBSYSTEM_ISSUE_CATEGORY_ICON: Record<
   repo: FolderGit2,
   construct: Component,
   'static-topology': Network,
-  'dynamic-topology': Server,
+  'dynamic-topology': AppWindow,
   trail: Route,
 };
 

package/src/subsystem/SubsystemComponentGraph.tsx

@@ -1140,15 +1140,18 @@ function Inner({ components, trails, graphifyRelations, orderByLine, initialTrai
     [trails],
   );
 
-  // Per-node diagnostics badge: fold each component-targeted finding that maps
-  // to a verification rung into one badge per node — worst severity wins, the
-  // chip shows the earliest failing rung, and the count tallies the findings.
+  // Per-node diagnostics badge: fold each component-targeted finding into one
+  // badge per node — worst severity wins, the chip shows the earliest failing
+  // rung, and the count tallies the findings. A finding with no construct rung
+  // still badges the node when it carries a dedicated kind icon (e.g. a C4
+  // process gap): the chip wears the kind's icon instead of a rung's, so the
+  // node says "diagnostics here" for every finding the sidebar lists.
   const issueBadgeByAlias = useMemo(() => {
     const map = new Map<string, SubsystemNodeIssue>();
     if (!issues?.length) return map;
     for (const issue of issues) {
       const rung = issueRung(issue.kind);
-      if (!rung) continue;
+      if (!rung && !ISSUE_KIND_ICON[issue.kind]) continue;
       const comp = issueComponent(issue);
       if (!comp) continue;
       const prev = map.get(comp.alias);
@@ -1158,12 +1161,27 @@ function Inner({ components, trails, graphifyRelations, orderByLine, initialTrai
             ? 'error'
             : 'info',
         rung:
-          prev != null && ISSUE_RUNG_ORDER[prev.rung] <= ISSUE_RUNG_ORDER[rung]
-            ? prev.rung
-            : rung,
+          rung == null
+            ? prev?.rung
+            : prev?.rung != null &&
+                ISSUE_RUNG_ORDER[prev.rung] <= ISSUE_RUNG_ORDER[rung]
+              ? prev.rung
+              : rung,
         count: (prev?.count ?? 0) + 1,
       });
     }
+    // A rung finding wins the chip; only rung-less nodes wear a kind icon —
+    // the first kind-iconed finding the sidebar lists for that node.
+    for (const [alias, badge] of map) {
+      if (badge.rung != null) continue;
+      const kinded = issues.find(
+        (i) =>
+          !issueRung(i.kind) &&
+          ISSUE_KIND_ICON[i.kind] &&
+          issueComponent(i)?.alias === alias,
+      );
+      if (kinded) map.set(alias, { ...badge, kind: kinded.kind });
+    }
     return map;
   }, [issues, issueComponent]);
 

package/src/subsystem/model.ts

@@ -1135,8 +1135,19 @@ export type SubsystemIssueRung =
 export interface SubsystemNodeIssue {
   /** Worst severity on the node — `error` (contradicts source) beats `info`. */
   severity: 'error' | 'info';
-  /** Earliest failing rung across the node's findings. */
-  rung: SubsystemIssueRung;
+  /**
+   * Earliest failing rung across the node's findings. Absent when none of the
+   * node's findings sit on the construct ladder — a rung-less finding (e.g. a
+   * process gap) carries its audit `kind` instead.
+   */
+  rung?: SubsystemIssueRung;
+  /**
+   * The audit kind of the node's finding when that finding has no construct
+   * rung: the chip wears the kind's icon (`ISSUE_KIND_ICON`) rather than a
+   * rung's. Set only when `rung` is absent — a rung finding is more specific
+   * about where the construct fails, so it wins the chip.
+   */
+  kind?: string;
   /** Total findings on this node. */
   count: number;
 }

package/src/subsystem/nodes.tsx

@@ -46,6 +46,7 @@ import {
 import { componentColor } from '../pierre/constructColors';
 import { resolvePierreSyntaxThemeName } from '../pierre/pierreSyntaxTheme';
 import { ISSUE_KIND_ICON, ISSUE_RUNG_ICON } from './IssueList';
+import { Search } from 'lucide-react';
 import type { LucideIcon } from 'lucide-react';
 
 export const CONSTRUCT_LABEL: Record<string, string> = {
@@ -122,11 +123,13 @@ function useSubsystemCallbacks(): SubsystemGraphCallbacks {
 
 /**
  * The diagnostics overlay for a component node: the node's own border turns
- * dotted (see the node's `borderStyle`) and an earliest-failing-rung corner
- * chip (file → symbol → declaration → type → signature) carries the severity
- * color, with a count when the node has more than one finding. The chip is
- * purely additive and non-interactive; the border stays construct-colored, so
- * severity never has to compete with the construct palette.
+ * dotted (see the node's `borderStyle`) and a severity-colored corner chip
+ * carries the count. The chip's icon is the earliest-failing construct rung
+ * (file → symbol → declaration → type → signature); a finding with no rung
+ * (e.g. a C4 process gap) wears its kind icon instead — see
+ * `SubsystemNodeIssue.kind`. The chip is purely additive and non-interactive;
+ * the border stays construct-colored, so severity never has to compete with
+ * the construct palette.
  */
 function NodeIssueOverlay({ issue }: { issue: SubsystemNodeIssue }) {
   const { theme } = useTheme();
@@ -134,10 +137,15 @@ function NodeIssueOverlay({ issue }: { issue: SubsystemNodeIssue }) {
   const color = isError
     ? (theme.colors.error ?? '#e5534b')
     : (theme.colors.warning ?? '#d4a017');
+  const Icon = issue.rung
+    ? ISSUE_RUNG_ICON[issue.rung]
+    : issue.kind
+      ? (ISSUE_KIND_ICON[issue.kind] ?? Search)
+      : Search;
   return (
     <IssueChip
       color={color}
-      Icon={ISSUE_RUNG_ICON[issue.rung]}
+      Icon={Icon}
       count={issue.count}
       anchor={{ right: -9, bottom: -8 }}
     />

package/src/utils/elkLayout.test.ts

@@ -16,10 +16,126 @@ import {
   fractionAlongPath,
   planCompoundGroups,
   getElkOptions,
+  absoluteBoundsOf,
+  flowPositionOf,
   type Point,
 } from './elkLayout';
 import { EDGE_LABEL_WIDTH, EDGE_LABEL_SIDE_PADDING } from './edgeLabel';
 
+/**
+ * A synthetic laid-out result standing in for the drill-down's open layout: a
+ * compound parent at (12,12) with two children, a sibling container, and a
+ * flattened frame that never enters the ELK tree.
+ */
+function syntheticResult() {
+  const rect = (x: number, y: number, width: number, height: number) => ({
+    x, y, width, height,
+  });
+  return {
+    absoluteRects: new Map([
+      ['container:host', rect(12, 12, 508, 416)],
+      ['cmp:a', rect(24, 96, 140, 140)],
+      ['cmp:b', rect(24, 276, 140, 140)],
+      ['container:api', rect(576, 218, 250, 150)],
+    ]),
+    // A nested group's entry is parent-relative — the trap `flowPositionOf` avoids.
+    groupBounds: new Map([
+      ['container:host', rect(12, 12, 508, 416)],
+      ['container:api', rect(576, 218, 250, 150)],
+      ['system:acme', rect(-12, -52, 1152, 504)],
+    ]),
+  };
+}
+
+describe('absolute coordinate space', () => {
+  test('a root node keeps its absolute position', () => {
+    const r = syntheticResult();
+    expect(flowPositionOf(r, 'container:host')).toEqual({ x: 12, y: 12 });
+    expect(flowPositionOf(r, 'container:api')).toEqual({ x: 576, y: 218 });
+  });
+
+  // The bug this guards: a child's own position is already parent-relative, so
+  // subtracting the parent's absolute origin again pushed it out of its card.
+  test('a child is relative to its parent, offset exactly once', () => {
+    const r = syntheticResult();
+    expect(flowPositionOf(r, 'cmp:a', 'container:host')).toEqual({ x: 12, y: 84 });
+    expect(flowPositionOf(r, 'cmp:b', 'container:host')).toEqual({ x: 12, y: 264 });
+  });
+
+  test('children land inside the parent box they are nested in', () => {
+    const r = syntheticResult();
+    const box = absoluteBoundsOf(r, 'container:host')!;
+    for (const id of ['cmp:a', 'cmp:b']) {
+      const p = flowPositionOf(r, id, 'container:host')!;
+      const own = r.absoluteRects.get(id)!;
+      expect(p.x).toBeGreaterThanOrEqual(0);
+      expect(p.y).toBeGreaterThanOrEqual(0);
+      expect(p.x + own.width).toBeLessThanOrEqual(box.width);
+      expect(p.y + own.height).toBeLessThanOrEqual(box.height);
+    }
+  });
+
+  // A compound parent has no `result.nodes` entry at all, so anything reading
+  // positions from there leaves it on its authored slot.
+  test('a compound parent gets a real position, not a fallback', () => {
+    const r = syntheticResult();
+    expect(flowPositionOf(r, 'container:host')).not.toBeUndefined();
+    expect(flowPositionOf(r, 'container:host')).toEqual(
+      r.absoluteRects.get('container:host') && { x: 12, y: 12 },
+    );
+  });
+
+  test('a flattened frame resolves from the synthesized bounds', () => {
+    // Not in absoluteRects — it never entered the ELK tree.
+    expect(syntheticResult().absoluteRects.has('system:acme')).toBe(false);
+    expect(absoluteBoundsOf(syntheticResult(), 'system:acme')).toEqual({
+      x: -12, y: -52, width: 1152, height: 504,
+    });
+  });
+
+  test('an unknown id has no position rather than a silent zero', () => {
+    expect(flowPositionOf(syntheticResult(), 'nope')).toBeUndefined();
+    expect(absoluteBoundsOf(syntheticResult(), 'nope')).toBeUndefined();
+  });
+
+  test('an unknown parent falls back to absolute, not to a wrong origin', () => {
+    expect(flowPositionOf(syntheticResult(), 'cmp:a', 'nope')).toEqual({ x: 24, y: 96 });
+  });
+});
+
+/**
+ * A card's FLIP offset is the difference between where it was and where the new
+ * layout puts it. If this is computed in the wrong space the card slides to a
+ * plausible-looking wrong place, which is what "the anchors shift" looks like.
+ */
+describe('morph offsets', () => {
+  interface Rect { x: number; y: number; width: number; height: number }
+  const offsetTo = (from: Rect, to: Rect) => ({
+    x: from.x - to.x,
+    y: from.y - to.y,
+  });
+
+  test('a card that moves is offset by exactly the move', () => {
+    // Closed: (330,182) 250x150. Open: the compound parent ELK fitted at (12,12).
+    const closed = { x: 330, y: 182, width: 250, height: 150 };
+    const open = { x: 12, y: 12, width: 508, height: 416 };
+    expect(offsetTo(closed, open)).toEqual({ x: 318, y: 170 });
+  });
+
+  test('a card that does not move gets no offset', () => {
+    const same = { x: 576, y: 218, width: 250, height: 150 };
+    expect(offsetTo(same, same)).toEqual({ x: 0, y: 0 });
+  });
+
+  test('an offset ignores size, because the card transitions its own size', () => {
+    // Growing in place must not shift the anchor: the card's width/height
+    // transition handles the size, a translate must stay 0.
+    const before = { x: 12, y: 12, width: 250, height: 150 };
+    const after = { x: 12, y: 12, width: 508, height: 416 };
+    expect(offsetTo(before, after)).toEqual({ x: 0, y: 0 });
+  });
+});
+
 describe('planCompoundGroups', () => {
   test('drops a single-leaf group by default and promotes its member', () => {
     const plan = planCompoundGroups(
@@ -130,6 +246,21 @@ describe('planCompoundGroups', () => {
     );
     expect(plan.built[0]!.minWidth).toBe(220);
   });
+
+  // `padTop` only reaches ELK if the plan carries it; when it was dropped here
+  // the parent's own header was silently overlaid by its first child.
+  test('carries padTop through to the plan', () => {
+    const plan = planCompoundGroups(
+      [{ id: 'mod', memberIds: ['a', 'b'], padTop: 84 }],
+      ['a', 'b'],
+    );
+    expect(plan.built[0]!.padTop).toBe(84);
+  });
+
+  test('leaves padTop unset when the group does not reserve chrome', () => {
+    const plan = planCompoundGroups([{ id: 'mod', memberIds: ['a', 'b'] }], ['a', 'b']);
+    expect(plan.built[0]!.padTop).toBeUndefined();
+  });
 });
 
 describe('elkLayout helper functions', () => {