@principal-ai/subsystems-react 0.37.5 → 0.37.7

package/src/subsystem/WalkthroughsPanel.tsx

@@ -13,7 +13,7 @@
 import { useCallback, useEffect, useRef, useState } from 'react';
 import type { DragEvent as ReactDragEvent } from 'react';
 import { useTheme } from '@principal-ade/industry-theme';
-import { ChevronDown, GripVertical, Pause, Play } from 'lucide-react';
+import { Check, ChevronDown, Copy, GripVertical, Pause, Play } from 'lucide-react';
 import {
   PROPOSED_COLOR,
   reorderTargetIndex,
@@ -21,10 +21,17 @@ import {
   walkthroughStepGraphEdgeId,
   type SubsystemWalkthrough,
 } from './model';
+import { buildStepBrief } from './walkthroughBrief';
 
 /** Pause (ms) between steps when a walkthrough autoplays. */
 export const WALKTHROUGH_PLAY_PAUSE_MS = 2500;
 
+/** How long a step's copy button flashes its "copied" checkmark (ms). */
+export const STEP_COPY_FEEDBACK_MS = 2000;
+
+/** Square size (px) of a walkthrough header's Play/Collapse control. */
+const WALKTHROUGH_CONTROL_SIZE = 34;
+
 /** Drag state handed to a row's grip while a reorder is in flight. */
 interface WalkthroughReorderHandle {
   index: number;
@@ -93,6 +100,13 @@ function WalkthroughFlow({
   const [gripHover, setGripHover] = useState(false);
   const [hoveredStep, setHoveredStep] = useState<number | null>(null);
   const stepButtonRefs = useRef<(HTMLButtonElement | null)[]>([]);
+  // Per-step copy affordance: revealed while a row is hovered or holds focus.
+  // `focusedStep` tracks focus-within (button or its copy control) so the icon
+  // stays put while the pointer or focus moves between them.
+  const [focusedStep, setFocusedStep] = useState<number | null>(null);
+  const [copyHoverStep, setCopyHoverStep] = useState<number | null>(null);
+  const [copiedStep, setCopiedStep] = useState<number | null>(null);
+  const copyTimerRef = useRef<number | null>(null);
   // Autoplay: stepping through the flow's steps with a pause between each.
   const [playing, setPlaying] = useState(false);
   const playTimerRef = useRef<number | null>(null);
@@ -109,6 +123,38 @@ function WalkthroughFlow({
   // eslint-disable-next-line react-hooks/exhaustive-deps
   useEffect(() => () => stopPlaying(), []);
 
+  const copyStep = useCallback(
+    (stepIndex: number) => {
+      const brief = buildStepBrief(walkthrough, stepIndex);
+      if (brief.length === 0) return;
+      const clipboard = navigator.clipboard;
+      if (!clipboard) return;
+      void clipboard
+        .writeText(brief)
+        .then(() => {
+          setCopiedStep(stepIndex);
+          if (copyTimerRef.current != null) {
+            window.clearTimeout(copyTimerRef.current);
+          }
+          copyTimerRef.current = window.setTimeout(
+            () => setCopiedStep(null),
+            STEP_COPY_FEEDBACK_MS,
+          );
+        })
+        .catch(() => {
+          // best-effort — show nothing when the clipboard is unavailable
+        });
+    },
+    [walkthrough],
+  );
+
+  useEffect(
+    () => () => {
+      if (copyTimerRef.current != null) window.clearTimeout(copyTimerRef.current);
+    },
+    [],
+  );
+
   // Native HTML5 drag suppresses mouse events, so a row hovered when the drag
   // began never gets its mouseleave — its hover styling would stick after the
   // drop. Reset every row's hover whenever a drag starts or ends.
@@ -172,7 +218,8 @@ function WalkthroughFlow({
           display: 'flex',
           alignItems: 'center',
           gap: 4,
-          padding: '0 16px',
+          height: WALKTHROUGH_CONTROL_SIZE,
+          padding: '0 0 0 16px',
           background: wholeFlowActive || headerHover ? hoverBg : 'transparent',
           transition: 'background 120ms ease',
         }}
@@ -198,7 +245,7 @@ function WalkthroughFlow({
             display: 'flex',
             alignItems: 'center',
             minWidth: 0,
-            padding: '10px 0',
+            padding: 0,
             border: 'none',
             background: 'transparent',
             textAlign: 'left',
@@ -236,11 +283,11 @@ function WalkthroughFlow({
               alignItems: 'center',
               justifyContent: 'center',
               flexShrink: 0,
-              width: 22,
-              height: 22,
+              alignSelf: 'stretch',
+              width: WALKTHROUGH_CONTROL_SIZE,
               padding: 0,
               border: 'none',
-              borderRadius: 4,
+              borderRadius: 0,
               background: playing || playHover ? theme.colors.border : 'transparent',
               color: playing || playHover ? theme.colors.text : muted,
               cursor: 'pointer',
@@ -265,11 +312,11 @@ function WalkthroughFlow({
               alignItems: 'center',
               justifyContent: 'center',
               flexShrink: 0,
-              width: 22,
-              height: 22,
+              alignSelf: 'stretch',
+              width: WALKTHROUGH_CONTROL_SIZE,
               padding: 0,
               border: 'none',
-              borderRadius: 4,
+              borderRadius: 0,
               background: collapseHover ? theme.colors.border : 'transparent',
               color: collapseHover ? theme.colors.text : muted,
               cursor: 'pointer',
@@ -298,7 +345,7 @@ function WalkthroughFlow({
               display: 'inline-flex',
               alignItems: 'center',
               flexShrink: 0,
-              marginRight: -8,
+              marginRight: 8,
               padding: '2px 0',
               color: gripHover || reorder.isDragging ? theme.colors.text : muted,
               cursor: reorder.isDragging ? 'grabbing' : 'grab',
@@ -320,65 +367,121 @@ function WalkthroughFlow({
           {walkthrough.steps.map((step, i) => {
             const stepActive = active !== null && active.stepIndex === i;
             const proposed = stepProposed(step.from, step.to);
+            const revealed =
+              stepActive || hoveredStep === i || focusedStep === i || copiedStep === i;
+            const copied = copiedStep === i;
+            const copyHovered = copyHoverStep === i;
             return (
-              <button
+              <div
                 key={`${walkthroughStepGraphEdgeId(step)}-${i}`}
-                ref={(el) => {
-                  stepButtonRefs.current[i] = el;
-                }}
-                type="button"
-                title={proposed ? 'Step touches a proposed component' : undefined}
-                onMouseEnter={() => {
-                  setHoveredStep(i);
-                  onHoverStep(walkthrough, i);
-                }}
-                onClick={() => onFocusStep(walkthrough, i)}
-                style={{
-                  display: 'flex',
-                  alignItems: 'center',
-                  gap: 8,
-                  minWidth: 0,
-                  padding: '8px 8px 8px 17px',
-                  textAlign: 'left',
-                  borderRadius: 0,
-                  border: 'none',
-                  outline: 'none',
-                  background: stepActive || hoveredStep === i ? hoverBg : 'transparent',
-                  cursor: 'pointer',
-                  transition: 'background 120ms ease',
+                style={{ position: 'relative' }}
+                onFocus={() => setFocusedStep(i)}
+                onBlur={(e) => {
+                  if (!e.currentTarget.contains(e.relatedTarget as Node | null)) {
+                    setFocusedStep((cur) => (cur === i ? null : cur));
+                  }
                 }}
               >
-                <span
-                  style={{
-                    flexShrink: 0,
-                    width: 14,
-                    fontSize: theme.fontSizes[0],
-                    fontFamily: theme.fonts.monospace,
-                    fontWeight: proposed ? 700 : undefined,
-                    color: proposed
-                      ? PROPOSED_COLOR
-                      : stepActive
-                        ? theme.colors.text
-                        : muted,
+                <button
+                  ref={(el) => {
+                    stepButtonRefs.current[i] = el;
                   }}
-                >
-                  {i + 1}
-                </span>
-                <span
+                  type="button"
+                  title={proposed ? 'Step touches a proposed component' : undefined}
+                  onMouseEnter={() => {
+                    setHoveredStep(i);
+                    onHoverStep(walkthrough, i);
+                  }}
+                  onClick={() => onFocusStep(walkthrough, i)}
                   style={{
-                    flex: 1,
+                    display: 'flex',
+                    alignItems: 'center',
+                    gap: 8,
                     minWidth: 0,
-                    overflow: 'hidden',
-                    textOverflow: 'ellipsis',
-                    whiteSpace: 'nowrap',
-                    fontSize: theme.fontSizes[1],
-                    fontFamily: theme.fonts.monospace,
-                    color: proposed ? PROPOSED_COLOR : theme.colors.text,
+                    width: '100%',
+                    padding: '8px 36px 8px 17px',
+                    textAlign: 'left',
+                    borderRadius: 0,
+                    border: 'none',
+                    outline: 'none',
+                    background: stepActive || hoveredStep === i ? hoverBg : 'transparent',
+                    cursor: 'pointer',
+                    transition: 'background 120ms ease',
                   }}
                 >
-                  {step.symbol}
-                </span>
-              </button>
+                  <span
+                    style={{
+                      flexShrink: 0,
+                      width: 14,
+                      fontSize: theme.fontSizes[0],
+                      fontFamily: theme.fonts.monospace,
+                      fontWeight: proposed ? 700 : undefined,
+                      color: proposed
+                        ? PROPOSED_COLOR
+                        : stepActive
+                          ? theme.colors.text
+                          : muted,
+                    }}
+                  >
+                    {i + 1}
+                  </span>
+                  <span
+                    style={{
+                      flex: 1,
+                      minWidth: 0,
+                      overflow: 'hidden',
+                      textOverflow: 'ellipsis',
+                      whiteSpace: 'nowrap',
+                      fontSize: theme.fontSizes[1],
+                      fontFamily: theme.fonts.monospace,
+                      color: proposed ? PROPOSED_COLOR : theme.colors.text,
+                    }}
+                  >
+                    {step.symbol}
+                  </span>
+                </button>
+                {revealed && (
+                  <button
+                    type="button"
+                    aria-label={`Copy step ${i + 1} of ${walkthrough.title} for an agent`}
+                    title={copied ? 'Copied' : 'Copy this step for an agent'}
+                    onMouseDown={(e) => e.preventDefault()}
+                    onMouseEnter={() => setCopyHoverStep(i)}
+                    onMouseLeave={() =>
+                      setCopyHoverStep((cur) => (cur === i ? null : cur))
+                    }
+                    onClick={() => copyStep(i)}
+                    style={{
+                      position: 'absolute',
+                      right: 0,
+                      top: 0,
+                      bottom: 0,
+                      display: 'inline-flex',
+                      alignItems: 'center',
+                      justifyContent: 'center',
+                      width: 'auto',
+                      aspectRatio: '1 / 1',
+                      padding: 0,
+                      border: 'none',
+                      borderRadius: 0,
+                      background: copied
+                        ? 'rgba(16,185,129,0.12)'
+                        : copyHovered
+                          ? theme.colors.border
+                          : 'transparent',
+                      color: copied ? '#10b981' : copyHovered ? theme.colors.text : muted,
+                      cursor: 'pointer',
+                      transition: 'background 120ms ease, color 120ms ease',
+                    }}
+                  >
+                    {copied ? (
+                      <Check size={12} strokeWidth={2} />
+                    ) : (
+                      <Copy size={12} strokeWidth={2} />
+                    )}
+                  </button>
+                )}
+              </div>
             );
           })}
         </div>

package/src/subsystem/model.ts

@@ -963,6 +963,8 @@ export interface SubsystemGroupNodeData extends Record<string, unknown> {
   region: SubsystemProcessRegion;
   /** True while the region's members are dimmed by flow focus. */
   dimmed?: boolean;
+  /** Host-supplied frame color override; falls back to the derived color. */
+  color?: string;
 }
 
 export type SubsystemGraphNode =
@@ -1032,17 +1034,17 @@ export function isWalkthroughMechanism(
 }
 
 export const MECHANISM_COLOR: Record<SubsystemEdgeMechanism, string> = {
-  calls: '#4ec9b0', // teal
+  calls: '#22c55e', // green
   extends: '#b48ead', // purple
   inherits: '#9b6fd0', // purple
   implements: '#c586c0', // magenta
   mixes_in: '#d474a8', // pink-magenta
   uses: '#e3b341', // gold
   method: '#c586c0', // magenta
-  references: '#e07a5f', // terracotta
-  feeds: '#22c55e', // green — data-flow into a processor
-  produces: '#e07a5f', // terracotta — emits an output type
-  writes: '#2f9e44', // deep green — mutates retained state
+  references: '#3b82f6', // blue
+  feeds: '#4ec9b0', // teal — data-flow into a processor
+  produces: '#a78bfa', // violet — emits an output type
+  writes: '#e8853a', // orange — mutates retained state
   reads: '#0ea5e9', // sky — pulls from retained state
   watches: '#9ca3af', // gray — observes, owns nothing
   'registers-into': '#ff6b35', // orange
@@ -1186,7 +1188,7 @@ export function packageColor(name: string): string {
  *  are the only surface using it, but pick a distinct value if roles ever
  *  take over node borders. */
 export const ROLE_COLOR: Record<SubsystemComponentRole, string> = {
-  entry: '#ff6b35', // orange — boundary element
+  entry: '#c0c0c0', // silver — boundary element
   service: '#0893d2', // blue — external system
 };
 

package/src/subsystem/nodes.tsx

@@ -359,7 +359,8 @@ export function SubsystemGroupNode(props: NodeProps<Node<SubsystemGroupNodeData,
     selected?: boolean;
   };
   const region = data.region;
-  const color = packageColor(region?.key ?? 'process');
+  // Explicit host override wins over the derived (hash-based) frame color.
+  const color = data.color ?? packageColor(region?.key ?? 'process');
   const dimmed = data.dimmed === true;
   const hidden = (data as { hidden?: boolean }).hidden === true;
   // Label is the region identity alone (path / process key / owner/name).

package/src/subsystem/toC4.test.ts

@@ -0,0 +1,121 @@
+import { describe, expect, test } from 'bun:test';
+import {
+  toC4,
+  deriveRepoKey,
+  labelFromPurl,
+  isGroundedComponent,
+} from './toC4';
+import type { SubsystemModelDocument } from './model';
+
+const REPO = 'pkg:github/acme/repo';
+
+const doc: SubsystemModelDocument = {
+  components: [
+    { alias: 'a', name: 'Alpha', construct: 'function', file: 'src/a.ts', purl: `${REPO}#src/a.ts`, process: 'p1' },
+    { alias: 'b', name: 'Beta', construct: 'function', file: 'src/b.ts', purl: `${REPO}#src/b.ts`, process: 'p1' },
+    { alias: 's', name: 'Cache', construct: 'store', file: 'src/s.ts', purl: `${REPO}#src/s.ts`, process: 'p1' },
+    { alias: 'c', name: 'Gamma', construct: 'function', file: 'src/c.ts', purl: `${REPO}#src/c.ts`, process: 'p2' },
+    { alias: 'x', name: 'Gist API', construct: 'external', file: '', purl: 'external:api.github.com/gists' },
+    { alias: 'agent', name: 'Maintenance agent', construct: 'custom_entity', file: '', purl: 'external' },
+  ],
+  relations: [
+    { id: 'r1', from: 'a', to: 'b', relationType: 'method' }, // intra p1
+    { id: 'r2', from: 'a', to: 'c', relationType: 'references' },
+    { id: 'r3', from: 'b', to: 'c', relationType: 'references' },
+    { id: 'r4', from: 'a', to: 'x', relationType: 'references' },
+  ],
+  walkthroughs: [
+    {
+      id: 'w1',
+      title: 'flow',
+      steps: [
+        { from: 'b', to: 'c', mechanism: 'calls', file: 'src/b.ts', line: 1, purl: `${REPO}#src/b.ts`, symbol: 'Beta' },
+        { from: 'a', to: 'c', mechanism: 'calls', file: 'src/a.ts', line: 2, purl: `${REPO}#src/a.ts`, symbol: 'Alpha' },
+        { from: 'a', to: 'agent', mechanism: 'calls', file: 'src/a.ts', line: 3, purl: `${REPO}#src/a.ts`, symbol: 'Alpha' },
+      ],
+    },
+  ],
+};
+
+describe('helpers', () => {
+  test('deriveRepoKey ignores external purls', () => {
+    expect(deriveRepoKey(doc)).toBe(REPO);
+  });
+
+  test('labelFromPurl trims scheme and keeps owner/name', () => {
+    expect(labelFromPurl('pkg:github/acme/repo#src/a.ts')).toBe('acme/repo');
+    expect(labelFromPurl('external:api.github.com/gists')).toBe('api.github.com/gists');
+  });
+
+  test('isGroundedComponent excludes externals and entities', () => {
+    expect(isGroundedComponent(doc.components[0]!)).toBe(true);
+    expect(isGroundedComponent(doc.components[4]!)).toBe(false);
+    expect(isGroundedComponent(doc.components[5]!)).toBe(false);
+  });
+});
+
+describe('container view', () => {
+  const model = toC4(doc, { view: 'container', systemLabel: 'Acme' });
+
+  test('system is the repo, containers are processes', () => {
+    expect(model.system.id).toBe(`system:${REPO}`);
+    expect(model.system.label).toBe('Acme');
+    expect(model.nodes.map((n) => n.id).sort()).toEqual(
+      [`container:p1`, `container:p2`, `external:external:api.github.com/gists`, `actor:agent`].sort(),
+    );
+  });
+
+  test('container members and store flag', () => {
+    const p1 = model.nodes.find((n) => n.id === 'container:p1')!;
+    expect(p1.members.sort()).toEqual(['a', 'b', 's']);
+    expect(p1.isStore).toBe(true);
+  });
+
+  test('one system group holds the container nodes', () => {
+    expect(model.groups).toHaveLength(1);
+    expect(model.groups[0]!.kind).toBe('system');
+    expect(model.groups[0]!.memberIds.sort()).toEqual(['container:p1', 'container:p2']);
+  });
+
+  test('edges roll up and intra-container edges drop', () => {
+    const byId = Object.fromEntries(model.edges.map((e) => [e.id, e]));
+    // a->b is intra-p1 — dropped.
+    expect(model.edges.some((e) => e.source === e.target)).toBe(false);
+    const rel = byId['relationship:container:p1\u0000container:p2']!;
+    expect(rel.kind).toBe('relationship');
+    expect(rel.count).toBe(2); // r2 + r3
+    const flow = byId['flow:container:p1\u0000container:p2']!;
+    expect(flow.count).toBe(2); // a->c + b->c
+    expect(byId['relationship:container:p1\u0000external:external:api.github.com/gists']).toBeDefined();
+    expect(byId['flow:container:p1\u0000actor:agent']).toBeDefined();
+    expect(model.edges).toHaveLength(4);
+  });
+});
+
+describe('component view', () => {
+  const model = toC4(doc, { view: 'component' });
+
+  test('components parent to their container; externals stay root', () => {
+    const a = model.nodes.find((n) => n.id === 'component:a')!;
+    expect(a.parentId).toBe('container:p1');
+    const c = model.nodes.find((n) => n.id === 'component:c')!;
+    expect(c.parentId).toBe('container:p2');
+    expect(model.nodes.map((n) => n.id).sort()).toEqual(
+      ['component:a', 'component:b', 'component:s', 'component:c', 'external:external:api.github.com/gists', 'actor:agent'].sort(),
+    );
+  });
+
+  test('nested groups: containers nest in the system', () => {
+    const p1 = model.groups.find((g) => g.id === 'container:p1')!;
+    expect(p1.parentId).toBe(`system:${REPO}`);
+    expect(p1.memberIds.sort()).toEqual(['component:a', 'component:b', 'component:s']);
+    const system = model.groups.find((g) => g.kind === 'system')!;
+    expect(system.memberIds.sort()).toEqual(['container:p1', 'container:p2']);
+  });
+
+  test('intra-container but cross-component edges survive', () => {
+    // a->b (same container, different components) survives at component level.
+    expect(model.edges.some((e) => e.source === 'component:a' && e.target === 'component:b')).toBe(true);
+    expect(model.edges.some((e) => e.source === e.target)).toBe(false);
+  });
+});