@principal-ai/subsystems-react 0.50.0 → 0.51.1

package/src/subsystem/C4NodeCard.tsx

@@ -0,0 +1,301 @@
+/**
+ * C4NodeCard — the box an element draws as, with nothing else.
+ *
+ * Extracted from `C4Graph.tsx` so the visual encoding can be inspected,
+ * reviewed, and unit-tested without standing up a graph. React Flow supplies
+ * edges and hit-testing; this supplies the reading surface.
+ *
+ * The encoding has one job: make confirmation state legible at a glance. A box
+ * nobody has looked at must not read the same as a box a person signed off.
+ * Kind says what the box is — shape, size, and a written tag — and everything
+ * else in C4 notation (technology, description) is surfaced in the order a
+ * reader wants it.
+ */
+
+import { useTheme } from '@principal-ade/industry-theme';
+import { describeConstructBreakdown } from './model';
+import type { C4Node } from './c4';
+
+/**
+ * Card box for a container: a wide rectangle. A container carries four things
+ * at once (tag, label, type + technology, and the notation gap it still has),
+ * and a strip would force the last two to truncate.
+ */
+export const NODE_W = 210;
+export const NODE_H = 138;
+
+/**
+ * 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.
+ */
+export const COMPONENT_SIZE = 132;
+
+/**
+ * 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.
+ */
+export function nodeSize(node: C4Node): { width: number; height: number } {
+  return node.kind === 'component'
+    ? { width: COMPONENT_SIZE, height: COMPONENT_SIZE }
+    : { width: NODE_W, height: NODE_H };
+}
+
+/**
+ * Fixed slot heights, so rows line up across every card regardless of which
+ * optional fields are present. Without these a card missing its notation-gap
+ * marker is two lines shorter and a row of cards reads as ragged.
+ */
+const LABEL_SLOT_H = 40;
+const GAP_SLOT_H = 18;
+
+type Theme = ReturnType<typeof useTheme>['theme'];
+
+export interface NodeStyle {
+  color: string;
+  dash: 'solid' | 'dashed' | 'dotted';
+  width: number;
+}
+
+/**
+ * Border style for one node: colour, dash and weight, from confirmation state
+ * and level.
+ *
+ * One axis per channel, so nothing is said twice and nothing is contradicted:
+ *
+ *   colour + dash  → confirmation state (the primary axis)
+ *   weight         → C4 level, as a grayscale redundancy for the square
+ *   shape + size   → C4 kind (`nodeShape`, `nodeSize`)
+ *
+ * State owning the dash is deliberate. An earlier build gave the dash to kind
+ * and drew proposed boxes solid, quietly contradicting the one thing the
+ * confirm UI needs a reader to see. Kind now says itself through shape, and
+ * the border says who vouched for it.
+ */
+export function nodeStyle(node: C4Node, theme: Theme, selected = false): NodeStyle {
+  const muted = theme.colors.border ?? '#555';
+  if (selected) return { color: theme.colors.primary ?? '#5aa', dash: 'solid', width: 3 };
+
+  // Border weight carries the level, so a component stays a component even
+  // in grayscale or for a reader who cannot separate the hues.
+  const weight = node.kind === 'component' ? 1 : 2;
+
+  switch (node.state) {
+    case 'accepted':
+      // Solid and saturated — part of the architecture now.
+      return { color: theme.colors.primary ?? '#4ec9b0', dash: 'solid', width: weight };
+    case 'proposed':
+      // Dashed — an agent asked; a human has not answered.
+      return { color: theme.colors.warning ?? '#e8a33a', dash: 'dashed', width: weight };
+    case 'rejected':
+      // Should never be drawn (buildC4Model drops it); belt-and-braces.
+      return { color: muted, dash: 'dotted', width: 1 };
+  }
+}
+
+function baseName(path: string): string {
+  const parts = path.split('/').filter(Boolean);
+  return parts[parts.length - 1] ?? path;
+}
+
+/**
+ * The kind + technology line under the label.
+ *
+ * A container shows its `containerKind` (application / data-store / queue);
+ * C4 has no kind for the other three, so they show technology or nothing.
+ */
+export function nodeSubtitle(node: C4Node): string {
+  const parts = [node.containerKind, node.technology].filter(Boolean);
+  if (parts.length > 0) return parts.join(' · ');
+
+  // No confirmed attributes: fall back to what the document told us.
+  if (node.kind === 'component') {
+    return `${node.component?.construct ?? 'code'}${node.component?.file ? ` · ${baseName(node.component.file)}` : ''}`;
+  }
+  const count = node.members.length;
+  return `${describeConstructBreakdown(node.constructs)}${count > 0 ? ` · ${count} component${count === 1 ? '' : 's'}` : ''}`;
+}
+
+/**
+ * What the box IS — its C4 kind. An accepted container is still a container;
+ * collapsing the two is what once made containers and components unreadable.
+ * Confirmation state is a separate axis carried by the border (see
+ * `nodeStyle`), not by a word on the card.
+ */
+export function nodeTag(node: C4Node): string {
+  return node.kind;
+}
+
+/** How a box is drawn. Shape carries the C4 kind, independent of colour. */
+export type C4ShapeKind = 'rect' | 'square' | 'pill';
+
+export interface NodeShape {
+  kind: C4ShapeKind;
+  /** Corner radius, for the shapes that use one. */
+  radius: number;
+}
+
+/**
+ * Shape cue for the C4 kind, independent of colour and dash — both of which
+ * belong to confirmation state.
+ *
+ * The convention:
+ *
+ *   container        wide rectangle, sharp corners — a runtime boundary
+ *   component        square — a part inside one (see `nodeSize`)
+ *   external system  wide rectangle, rounded     — someone else's system
+ *   person           pill                          — not a box at all
+ *
+ * An external system is separated from a container by radius alone, which is
+ * a weak cue. That is deliberate rather than an oversight: the border dash is
+ * the only channel that could say "outside our control" loudly, and it is
+ * already spent on proposed-vs-accepted. The kind tag says it in words, and
+ * the frame position says it structurally.
+ */
+export function nodeShape(node: C4Node): NodeShape {
+  switch (node.kind) {
+    case 'person':
+      return { kind: 'pill', radius: NODE_H / 2 };
+    case 'external-system':
+      return { kind: 'rect', radius: 14 };
+    case 'component':
+      return { kind: 'square', radius: 6 };
+    default:
+      return { kind: 'rect', radius: 4 };
+  }
+}
+
+/**
+ * The gaps the C4 notation still wants on this element, named rather than left
+ * to be noticed.
+ *
+ * Containers are where the notation is strictest: it requires a technology and
+ * a description on every one. A component needs a technology too, but a
+ * component drawn without a parent already reports `unknown_container`, and
+ * that is the question worth asking first.
+ */
+export function nodeMissing(node: C4Node): string[] {
+  if (node.kind !== 'container') return [];
+  const missing: string[] = [];
+  if (!node.technology) missing.push('technology');
+  if (!node.description) missing.push('description');
+  return missing;
+}
+
+export interface C4NodeCardProps {
+  node: C4Node;
+  selected?: boolean;
+  /** Draw React Flow's edge handles. Off when rendering a bare gallery. */
+  handles?: React.ReactNode;
+  onClick?: () => void;
+}
+
+export function C4NodeCard({ node, selected = false, handles, onClick }: C4NodeCardProps) {
+  const { theme } = useTheme();
+  const muted = theme.colors.textMuted ?? theme.colors.textSecondary;
+  const style = nodeStyle(node, theme, selected);
+  const shape = nodeShape(node);
+  const missing = nodeMissing(node);
+
+  const size = nodeSize(node);
+
+  return (
+    <div
+      onClick={onClick}
+      style={{
+        width: size.width,
+        minHeight: size.height,
+        boxSizing: 'border-box',
+        display: 'flex',
+        flexDirection: 'column',
+        // Top-aligned, not centred: the number of lines varies (the notation-gap
+        // marker is conditional), and centring pushes the tag to a different
+        // height on every card. In a graph grid that makes the row unscannable.
+        justifyContent: 'flex-start',
+        gap: 3,
+        padding: '10px 12px',
+        borderRadius: shape.radius,
+        background: theme.colors.backgroundSecondary ?? theme.colors.background,
+        border: `${style.width} ${style.dash} ${style.color}`,
+        boxShadow: '0 1px 4px rgba(0,0,0,0.25)',
+        cursor: onClick ? 'pointer' : 'default',
+        fontFamily: theme.fonts.body,
+      }}
+    >
+      {/* The kind is what the box IS. Confirmation state is carried by the
+          border (see `nodeStyle`), not by a word: the card says what it is,
+          and the styling says who vouched for it. */}
+      <span
+        style={{
+          fontFamily: theme.fonts.monospace,
+          fontSize: theme.fontSizes[0],
+          color: style.color,
+          fontWeight: 600,
+          letterSpacing: 0.5,
+          textTransform: 'uppercase',
+          whiteSpace: 'nowrap',
+          overflow: 'hidden',
+          textOverflow: 'ellipsis',
+        }}
+      >
+        {nodeTag(node)}
+      </span>
+      {/* Two lines rather than an ellipsis: a truncated label hides the very
+          thing that distinguishes two containers from each other. The fixed
+          height reserves both lines even for a one-line label, so the subtitle
+          below sits at the same y on every card. */}
+      <span
+        style={{
+          fontWeight: 600,
+          fontSize: theme.fontSizes[2],
+          color: theme.colors.text,
+          lineHeight: 1.25,
+          height: LABEL_SLOT_H,
+          display: '-webkit-box',
+          WebkitLineClamp: 2,
+          WebkitBoxOrient: 'vertical',
+          overflow: 'hidden',
+        }}
+        title={node.label}
+      >
+        {node.label}
+      </span>
+      <span
+        style={{
+          fontFamily: theme.fonts.monospace,
+          fontSize: theme.fontSizes[0],
+          color: muted,
+          whiteSpace: 'nowrap',
+          overflow: 'hidden',
+          textOverflow: 'ellipsis',
+        }}
+        title={node.description ?? node.members.join(', ')}
+      >
+        {nodeSubtitle(node)}
+      </span>
+      {/* Reserved row: without it, a card with no notation gap is two lines
+          shorter and the row of cards reads as ragged. */}
+      <span style={{ height: GAP_SLOT_H }} aria-hidden="true" />
+      {missing.length > 0 && (
+        <span
+          title={`C4 requires a ${missing.join(' and a ')} on every container`}
+          style={{
+            fontFamily: theme.fonts.monospace,
+            fontSize: theme.fontSizes[0],
+            color: theme.colors.warning ?? '#e8a33a',
+            lineHeight: 1.3,
+            height: GAP_SLOT_H,
+            display: '-webkit-box',
+            WebkitLineClamp: 2,
+            WebkitBoxOrient: 'vertical',
+            overflow: 'hidden',
+          }}
+        >
+          needs {missing.join(' + ')}
+        </span>
+      )}
+      {handles}
+    </div>
+  );
+}

package/src/subsystem/DiagnosticToggle.tsx

@@ -28,6 +28,13 @@ export interface SubsystemDiagnostic {
   status: SubsystemDiagnosticStatus;
   /** Count shown beside the icon (e.g. error + warn findings). Hidden when 0/undefined. */
   issueCount?: number;
+  /**
+   * How many of the open findings carry a one-click deterministic fix (a
+   * re-pin, an adoptable signature fill, a unique Graphify file relocate).
+   * Badged on the icon so it's visible without expanding the list — the fixes
+   * live inside collapsed categories, so the count was previously invisible.
+   */
+  fixableCount?: number;
   /** Inputs changed since the report was produced. */
   stale?: boolean;
   /** A verification pass is running right now. */
@@ -55,7 +62,7 @@ export function diagnosticStatusColor(
 /** Human tooltip for the current diagnostic state. */
 export function diagnosticTitle(diagnostic: SubsystemDiagnostic): string {
   if (diagnostic.title) return diagnostic.title;
-  const { status, issueCount, stale, busy } = diagnostic;
+  const { status, issueCount, fixableCount, stale, busy } = diagnostic;
   let head: string;
   if (status === 'ok') head = 'Diagnostics: no issues';
   else if (status === 'issues')
@@ -69,9 +76,15 @@ export function diagnosticTitle(diagnostic: SubsystemDiagnostic): string {
         ? `Diagnostics: ${issueCount} unconfirmed`
         : 'Diagnostics: unconfirmed claims';
   else head = 'Diagnostics: not checked yet';
+  // Name the one-click count first when there is work a click can close —
+  // that's the actionable part of the list.
+  const fixable =
+    fixableCount != null && fixableCount > 0
+      ? `${fixableCount} fixable with one click`
+      : '';
   if (busy) return `${head} — checking…`;
-  if (stale) return `${head} (stale) — toggle the list`;
-  return `${head} — toggle the list`;
+  if (stale) return `${head} (stale) — toggle the list${fixable ? `, ${fixable}` : ''}`;
+  return `${head} — toggle the list${fixable ? `, ${fixable}` : ''}`;
 }
 
 export interface SubsystemDiagnosticToggleProps extends SubsystemDiagnostic {
@@ -82,6 +95,7 @@ export interface SubsystemDiagnosticToggleProps extends SubsystemDiagnostic {
 export function SubsystemDiagnosticToggle({
   status,
   issueCount,
+  fixableCount = 0,
   stale = false,
   busy = false,
   active = false,
@@ -93,8 +107,20 @@ export function SubsystemDiagnosticToggle({
   const [hover, setHover] = useState(false);
   const muted = theme.colors.textMuted ?? theme.colors.textSecondary;
   const color = diagnosticStatusColor(status, theme.colors, muted);
-  const label = diagnosticTitle({ status, issueCount, stale, busy, active, ...rest });
+  const label = diagnosticTitle({
+    status,
+    issueCount,
+    fixableCount,
+    stale,
+    busy,
+    active,
+    ...rest,
+  });
   const showCount = issueCount != null && issueCount > 0;
+  // Green regardless of status: this marks "a click fixes this", not severity,
+  // and green is the same accent the per-finding Apply button uses.
+  const showFixable = fixableCount > 0 && !busy;
+  const fixableColor = theme.colors.success ?? '#2da44e';
   const background = active
     ? hexWithAlpha(color, hover ? 0.24 : 0.16)
     : hover
@@ -151,6 +177,34 @@ export function SubsystemDiagnosticToggle({
               }}
             />
           )}
+          {/* Fixable badge — superscript count on the icon's trailing edge.
+              Offset up-and-out from the `stale` dot so both read at once;
+              the badge is the call to action, the dot only a freshness note. */}
+          {showFixable && (
+            <span
+              aria-hidden
+              style={{
+                position: 'absolute',
+                top: -5,
+                right: -8,
+                minWidth: 12,
+                height: 12,
+                padding: '0 3px',
+                borderRadius: 6,
+                display: 'inline-flex',
+                alignItems: 'center',
+                justifyContent: 'center',
+                background: fixableColor,
+                color: theme.colors.background,
+                fontFamily: theme.fonts.monospace,
+                fontSize: 9,
+                fontWeight: 700,
+                lineHeight: 1,
+              }}
+            >
+              {fixableCount > 99 ? '99+' : fixableCount}
+            </span>
+          )}
         </span>
         {showCount && (
           <span

package/src/subsystem/FileDrawer.tsx

@@ -117,21 +117,46 @@ export function FileDrawer({
             userSelect: "none",
           }}
         >
+          {showProgress && progress != null && (
+            <div
+              role="img"
+              aria-label={`Step ${progress.index + 1} of ${progress.total}`}
+              style={{
+                display: "flex",
+                gap: 2,
+                flexShrink: 0,
+              }}
+            >
+              {Array.from({ length: progress.total }, (_, i) => (
+                <span
+                  key={i}
+                  style={{
+                    flex: 1,
+                    height: 2,
+                    borderRadius: 1,
+                    background:
+                      i <= progress.index
+                        ? theme.colors.primary
+                        : theme.colors.border,
+                  }}
+                />
+              ))}
+            </div>
+          )}
           <div
             style={{
               display: "flex",
               alignItems: "center",
               gap: 8,
-              padding: "6px 10px",
-              // With segments present they form the header's bottom edge, so
-              // only draw the hairline when there is nothing to stand in for it.
-              borderBottom: showProgress
-                ? "none"
-                : `1px solid ${theme.colors.border}`,
+              // Top runs deeper than the bottom so the title/label sits
+              // optically centered inside the sticky top edge.
+              padding: "10px 10px 8px",
+              // The header row is the last chrome row now, so its hairline is
+              // the boundary with the code below.
+              borderBottom: `1px solid ${theme.colors.border}`,
             }}
           >
             <span
-              title={title ?? undefined}
               style={{
                 flex: 1,
                 minWidth: 0,
@@ -197,33 +222,6 @@ export function FileDrawer({
               <X size={14} />
             </button>
           </div>
-          {showProgress && progress != null && (
-            <div
-              role="img"
-              aria-label={`Step ${progress.index + 1} of ${progress.total}`}
-              style={{
-                display: "flex",
-                gap: 2,
-                flexShrink: 0,
-                padding: "0 10px 6px",
-              }}
-            >
-              {Array.from({ length: progress.total }, (_, i) => (
-                <span
-                  key={i}
-                  style={{
-                    flex: 1,
-                    height: 2,
-                    borderRadius: 1,
-                    background:
-                      i <= progress.index
-                        ? theme.colors.primary
-                        : theme.colors.border,
-                  }}
-                />
-              ))}
-            </div>
-          )}
         </div>
         <div style={{ flex: 1, minHeight: 0, overflow: "auto" }}>
           {children}

package/src/subsystem/IssueList.tsx

@@ -233,7 +233,7 @@ export function humanizeIssueKind(kind: string): string {
 const KIND_LABEL: Record<string, string> = {
   missing_file: 'Construct declaration file missing',
   symbol_ambiguous: 'Multiple construct symbol matches',
-  symbol_unmatched: 'Construct symbol unconfirmed',
+  symbol_unmatched: 'Construct symbol missing',
   stale_declaration: 'Construct declaration drift',
   construct_mismatch: 'Construct type mismatch',
   construct_unconfirmed: 'Construct type unconfirmed',

package/src/subsystem/SubsystemComponentGraph.tsx

@@ -869,16 +869,24 @@ function Inner({ components, trails, graphifyRelations, orderByLine, initialTrai
   // the selected step until it does.
   const [visibleStepIndex, setVisibleStepIndex] = useState<number | null>(null);
   const drawerStepIndex = drawerTarget?.kind === 'trail' ? drawerTarget.stepIndex : null;
+  // Reset when the drawer switches trail (or closes) — synchronously, so the bar
+  // never paints the previous trail's position. A step change *within* the same
+  // trail is deliberately not reset: the code view scrolls to the new step and
+  // the viewport tracker carries the fill across that scroll. Resetting on step
+  // change flashed — the post-paint effect snapped the fill to the target, then
+  // Pierre's smooth scroll re-reported the old viewport, bouncing target → old →
+  // target.
+  const activeTrailId = focusedTrail?.id ?? null;
+  const [visibleTrailId, setVisibleTrailId] = useState(activeTrailId);
+  if (activeTrailId !== visibleTrailId) {
+    setVisibleTrailId(activeTrailId);
+    setVisibleStepIndex(null);
+  }
   const drawerProgress = useMemo(() => {
     if (drawerStepIndex == null || !focusedTrail) return null;
     return { index: visibleStepIndex ?? drawerStepIndex, total: focusedTrail.steps.length };
   }, [drawerStepIndex, focusedTrail, visibleStepIndex]);
 
-  // A new trail or step invalidates whatever the last scroll reported.
-  useEffect(() => {
-    setVisibleStepIndex(null);
-  }, [focusedTrail?.id, drawerStepIndex]);
-
   // Refresh selected component when the components list updates (e.g. verify
   // writes back declarationRef).
   useEffect(() => {