@principal-ai/subsystems-react 0.53.2 → 0.53.3

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/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 }}
     />