@principal-ai/subsystems-react 0.55.3 → 0.56.0

package/src/subsystem/TrailStepsNav.tsx

@@ -3,6 +3,10 @@ import type { CSSProperties } from 'react';
 import { ChevronRight, Route, X } from 'lucide-react';
 import { useTheme } from '@principal-ade/industry-theme';
 import type { SubsystemTrail } from './model';
+import {
+  trailStepDisplay,
+  type TrailComponentLabels,
+} from './trailStepDisplay';
 
 /**
  * TrailStepsNav — the trails side panel as a two-step slide: a list of trails,
@@ -41,14 +45,12 @@ export interface TrailStepsNavProps {
   onHoverStep: (trail: SubsystemTrail, stepIndex: number) => void;
   onHoverFlow: (trail: SubsystemTrail) => void;
   onLeaveStep: () => void;
-  /** Aliases of components marked `proposed` — a row whose steps touch one tints. */
-  proposedAliases?: ReadonlySet<string>;
+  /** Alias → component, for turning hops into human display names. */
+  componentByAlias?: TrailComponentLabels;
   /** Slide duration in ms. @default 340 */
   transitionMs?: number;
 }
 
-const PROPOSED_COLOR = 'darkgoldenrod';
-
 const PANE: CSSProperties = {
   position: 'absolute',
   inset: 0,
@@ -58,11 +60,6 @@ const PANE: CSSProperties = {
   willChange: 'transform',
 };
 
-function touchesProposed(trail: SubsystemTrail, proposed?: ReadonlySet<string>): boolean {
-  if (!proposed) return false;
-  return trail.steps.some((s) => proposed.has(s.from) || proposed.has(s.to));
-}
-
 export function TrailStepsNav({
   trails,
   focusedTrailId,
@@ -74,7 +71,7 @@ export function TrailStepsNav({
   onHoverStep,
   onHoverFlow,
   onLeaveStep,
-  proposedAliases,
+  componentByAlias,
   transitionMs = 340,
 }: TrailStepsNavProps) {
   const { theme } = useTheme();
@@ -131,7 +128,6 @@ export function TrailStepsNav({
       >
         <div style={{ flex: 1, minHeight: 0, overflowY: 'auto', padding: '0 0 12px' }}>
           {trails.map((trail) => {
-            const proposed = touchesProposed(trail, proposedAliases);
             const focusedRow = trail.id === focusedTrailId;
             const hovered = hoveredRow === trail.id;
             return (
@@ -177,7 +173,7 @@ export function TrailStepsNav({
                     fontSize: theme.fontSizes[1],
                     fontFamily: theme.fonts.monospace,
                     fontWeight: 600,
-                    color: proposed ? PROPOSED_COLOR : theme.colors.text,
+                    color: theme.colors.text,
                   }}
                 >
                   {trail.title}
@@ -251,7 +247,7 @@ export function TrailStepsNav({
                   fontSize: theme.fontSizes[1],
                   fontFamily: theme.fonts.monospace,
                   fontWeight: 600,
-                  color: touchesProposed(displayedTrail, proposedAliases) ? PROPOSED_COLOR : theme.colors.text,
+                  color: theme.colors.text,
                 }}
               >
                 {displayedTrail.title}
@@ -291,6 +287,7 @@ export function TrailStepsNav({
                 const hovered =
                   hoveredTrailStep?.trailId === displayedTrail.id &&
                   hoveredTrailStep.stepIndex === i;
+                const display = trailStepDisplay(step, componentByAlias);
                 return (
                   <button
                     key={`${step.from}->${step.to}-${i}`}
@@ -342,8 +339,9 @@ export function TrailStepsNav({
                             minWidth: 0,
                             overflowWrap: 'anywhere',
                             fontSize: theme.fontSizes[1],
-                            fontFamily: theme.fonts.monospace,
+                            fontFamily: theme.fonts.body,
                             color: theme.colors.text,
+                            lineHeight: 1.35,
                           }}
                         >
                           {step.annotation}
@@ -351,13 +349,14 @@ export function TrailStepsNav({
                       )}
                       <span
                         style={{
-                          fontSize: theme.fontSizes[0],
-                          fontFamily: theme.fonts.body,
-                          color: muted,
-                          lineHeight: 1.35,
+                          minWidth: 0,
+                          overflowWrap: 'anywhere',
+                          fontSize: theme.fontSizes[1],
+                          fontFamily: theme.fonts.monospace,
+                          color: theme.colors.text,
                         }}
                       >
-                        {step.symbol ?? step.from}
+                        {display.primary}
                       </span>
                     </span>
                   </button>

package/src/subsystem/TrailsPanel.test.tsx

@@ -9,6 +9,11 @@ import {
 } from './TrailsPanel';
 import type { SubsystemTrail } from './model';
 import { buildStepBrief } from './trailBrief';
+import {
+  buildStepEmphasisMap,
+  stepClaimKey,
+  type StepEmphasisRecord,
+} from './stepEmphasis';
 
 // Bun's happy-dom test environment needs `@happy-dom/global-registrator`, which
 // isn't installed here, so wire the DOM primitives React DOM + Testing Library
@@ -31,6 +36,12 @@ globals.cancelAnimationFrame = dom.cancelAnimationFrame.bind(dom);
 globals.localStorage = dom.localStorage;
 globals.sessionStorage = dom.sessionStorage;
 globals.matchMedia = dom.matchMedia.bind(dom);
+// themed-markdown measures its slide container; happy-dom has no ResizeObserver.
+globals.ResizeObserver = class {
+  observe() {}
+  unobserve() {}
+  disconnect() {}
+};
 
 
 const trails: SubsystemTrail[] = [
@@ -51,6 +62,22 @@ const trails: SubsystemTrail[] = [
   },
 ];
 
+const usesTrail: SubsystemTrail = {
+  id: 'uses-flow',
+  title: 'Uses flow',
+  steps: [
+    {
+      from: 'panel',
+      to: 'merge',
+      mechanism: 'uses',
+      file: 'src/list.tsx',
+      span: { startLine: 10, endLine: 12, contentHash: 'h' },
+      purl: 'pkg:github/acme/app#src/list.tsx',
+      symbol: 'ModelList',
+    },
+  ],
+};
+
 const writeText = mock(() => Promise.resolve());
 
 beforeEach(() => {
@@ -144,3 +171,125 @@ describe('TrailsPanel step copy', () => {
     expect(copy.getAttribute('title')).toBe('Copy this step for an agent');
   });
 });
+
+describe('TrailsPanel step semantics', () => {
+  test('calls leads with the caller frame', () => {
+    const { getByText, queryByText } = renderPanel();
+    expect(getByText('Login.submit')).toBeTruthy();
+    expect(queryByText(/calls →/)).toBeNull();
+  });
+
+  test('uses leads with the logical hop and shows the via site', () => {
+    const { getByText } = renderPanel({
+      trails: [usesTrail],
+      expandedTrails: new Set(['uses-flow']),
+      componentByAlias: new Map([
+        ['panel', { alias: 'panel', name: 'MaintenancePanel' }],
+        ['merge', { alias: 'merge', name: 'mergeProvenance' }],
+      ]),
+    });
+    expect(getByText('MaintenancePanel uses mergeProvenance')).toBeTruthy();
+  });
+
+  test('falls back to aliases when no component map is supplied', () => {
+    const { getByText } = renderPanel({
+      trails: [usesTrail],
+      expandedTrails: new Set(['uses-flow']),
+    });
+    expect(getByText('panel uses merge')).toBeTruthy();
+  });
+
+  test('uses the resolved target symbol as the callee', () => {
+    const withTarget: SubsystemTrail = {
+      ...usesTrail,
+      steps: [
+        {
+          ...usesTrail.steps[0]!,
+          target: {
+            purl: 'pkg:github/acme/app#src/store.ts',
+            file: 'src/store.ts',
+            symbol: 'Store.add',
+            span: { startLine: 3, endLine: 5, contentHash: 'h' },
+          },
+        },
+      ],
+    };
+    const { getByText } = renderPanel({
+      trails: [withTarget],
+      expandedTrails: new Set(['uses-flow']),
+      componentByAlias: new Map([
+        ['panel', { alias: 'panel', name: 'MaintenancePanel' }],
+        ['merge', { alias: 'merge', name: 'Store' }],
+      ]),
+    });
+    expect(getByText('MaintenancePanel uses Store.add')).toBeTruthy();
+  });
+
+});
+
+function emphasisRecord(
+  trailId: string,
+  stepIndex: number,
+  guidance?: string,
+): StepEmphasisRecord {
+  return {
+    trailId,
+    stepKey: stepClaimKey(trails[0]!.steps[stepIndex]!),
+    guidance,
+    provenance: { source: 'author', at: '2026-10-19T00:00:00.000Z' },
+  };
+}
+
+describe('TrailsPanel step emphasis', () => {
+  test('renders a marked star and the trail emphasis count', () => {
+    const emphasis = buildStepEmphasisMap([
+      emphasisRecord('auth-flow', 0, 'Why this step matters.'),
+    ]);
+    const { getByTitle } = renderPanel({ stepEmphasis: emphasis });
+    expect(getByTitle('1 emphasized step')).not.toBeNull();
+    expect(getByTitle('Key step')).not.toBeNull();
+  });
+
+  test('shows markdown guidance when the marked step is focused', () => {
+    const emphasis = buildStepEmphasisMap([
+      emphasisRecord('auth-flow', 0, '**Start here** because this row matters.'),
+    ]);
+    const { container } = renderPanel({
+      focusedTrailId: 'auth-flow',
+      focusedStepIndex: 0,
+      stepEmphasis: emphasis,
+    });
+    expect(container.textContent).toContain('Start here');
+    expect(container.textContent).toContain('because this row matters.');
+  });
+
+  test('Remove guidance toggles the mark off', () => {
+    const onRemoveStepEmphasis = mock(() => {});
+    const emphasis = buildStepEmphasisMap([
+      emphasisRecord('auth-flow', 0, 'Why this step matters.'),
+    ]);
+    const { getByText } = renderPanel({
+      focusedTrailId: 'auth-flow',
+      focusedStepIndex: 0,
+      stepEmphasis: emphasis,
+      onRemoveStepEmphasis,
+    });
+    fireEvent.click(getByText('Remove guidance'));
+    expect(onRemoveStepEmphasis).toHaveBeenCalledWith(trails[0], 0);
+  });
+
+  test('does not render guidance while the step is not focused', () => {
+    const emphasis = buildStepEmphasisMap([
+      emphasisRecord('auth-flow', 0, '**Start here** because this row matters.'),
+    ]);
+    const { container } = renderPanel({ stepEmphasis: emphasis });
+    expect(container.textContent).not.toContain('because this row matters.');
+  });
+
+  test('does not render a star for an unmarked step', () => {
+    const { queryByTitle } = renderPanel({
+      stepEmphasis: buildStepEmphasisMap([]),
+    });
+    expect(queryByTitle('Key step')).toBeNull();
+  });
+});

package/src/subsystem/TrailsPanel.tsx

@@ -13,20 +13,28 @@
 import { useCallback, useEffect, useRef, useState } from 'react';
 import type { DragEvent as ReactDragEvent } from 'react';
 import { useTheme } from '@principal-ade/industry-theme';
-import { Check, ChevronDown, Copy, Focus, GripVertical, Minimize2, Pause, Play } from 'lucide-react';
+import { Check, ChevronDown, Copy, Focus, GripVertical, Minimize2, Pause, Play, Star } from 'lucide-react';
+import { IndustryMarkdownSlide } from 'themed-markdown';
 import {
-  PROPOSED_COLOR,
   reorderTargetIndex,
   reorderTrails,
   trailStepGraphEdgeId,
   type SubsystemTrail,
-  type SubsystemTrailStep,
 } from './model';
 import { buildStepBrief } from './trailBrief';
+import { emphasisKey, type StepEmphasisMap } from './stepEmphasis';
+import {
+  trailStepDisplay,
+  type TrailComponentLabels,
+} from './trailStepDisplay';
+import { buildTrailStack } from './trailStack';
 
 /** Pause (ms) between steps when a trail autoplays. */
 export const TRAIL_PLAY_PAUSE_MS = 2500;
 
+/** Single accent for a key step (no kind vocabulary — the mark is a star). */
+const EMPHASIS_COLOR = '#f5a524';
+
 /**
  * Dwell time (ms) before a hover preview reaches the canvas.
  *
@@ -59,6 +67,7 @@ function TrailFlow({
   trail,
   collapsed,
   active,
+  focusedStepIndex,
   onToggleCollapsed,
   onFocusFlow,
   onClearFocus,
@@ -69,14 +78,21 @@ function TrailFlow({
   reorder,
   dragActive,
   isHoverSuppressed,
-  proposedAliases,
   layoutFocused,
   onToggleLayoutFocus,
+  stepEmphasis,
+  onRemoveStepEmphasis,
+  componentByAlias,
 }: {
   trail: SubsystemTrail;
   collapsed: boolean;
   /** `{ stepIndex: null }` = whole flow focused; `{ stepIndex }` = one step. */
   active: { stepIndex: number | null } | null;
+  /**
+   * The step currently focused by the host (not merely hovered). The guidance
+   * body follows this, so sweeping the pointer does not expand every step.
+   */
+  focusedStepIndex: number | null;
   onToggleCollapsed: (tlId: string) => void;
   onFocusFlow: (tl: SubsystemTrail) => void;
   onClearFocus: () => void;
@@ -91,29 +107,33 @@ function TrailFlow({
   dragActive?: boolean;
   /** True just after a drop; ignores the browser's synthetic hover until the pointer moves. */
   isHoverSuppressed?: () => boolean;
-  /**
-   * Aliases of components marked `proposed`. A row whose steps touch one gets
-   * its title tinted, and each such step (index and title) is tinted too
-   * (darkgoldenrod, same as the proposed node treatment).
-   */
-  proposedAliases?: ReadonlySet<string>;
   /** This flow's components are the only ones laid out right now. */
   layoutFocused?: boolean;
   /** Solo this flow's components in the layout, or restore the full model. */
   onToggleLayoutFocus?: (tl: SubsystemTrail) => void;
+  /**
+   * Host-owned emphasis augmentations for this model. Absent = no marks. The
+   * map is keyed by `emphasisKey` (trail + claim fingerprint), so reordering
+   * steps keeps marks attached.
+   */
+  stepEmphasis?: StepEmphasisMap;
+  /** Toggle a step's guidance off. Omit to hide the remove action. */
+  onRemoveStepEmphasis?: (tl: SubsystemTrail, stepIndex: number) => void;
+  /** Alias → component, for turning hops into human display names. */
+  componentByAlias?: TrailComponentLabels;
 }) {
   const { theme } = useTheme();
   const muted = theme.colors.textMuted ?? theme.colors.textSecondary;
   const hoverBg = theme.colors.background;
   const wholeFlowActive = active !== null && active.stepIndex === null;
-  // A step is "proposed" when it says so itself OR either endpoint component
-  // is proposed — the step flag covers planned seams whose endpoints already
-  // exist as real components.
-  const stepProposed = (step: SubsystemTrailStep) =>
-    step.proposed === true ||
-    (proposedAliases != null &&
-      (proposedAliases.has(step.from) || proposedAliases.has(step.to)));
-  const touchesProposed = trail.steps.some((s) => stepProposed(s));
+  // Emphasis is keyed by trail + claim fingerprint, so the count follows the
+  // steps through a reorder.
+  const emphasisCount = stepEmphasis
+    ? trail.steps.reduce(
+        (count, step) => count + (stepEmphasis.has(emphasisKey(trail.id, step)) ? 1 : 0),
+        0,
+      )
+    : 0;
   const [headerHover, setHeaderHover] = useState(false);
   const [collapseHover, setCollapseHover] = useState(false);
   const [playHover, setPlayHover] = useState(false);
@@ -316,12 +336,30 @@ function TrailFlow({
               fontSize: theme.fontSizes[1],
               fontFamily: theme.fonts.monospace,
               fontWeight: 600,
-              color: touchesProposed ? PROPOSED_COLOR : theme.colors.text,
+              color: theme.colors.text,
             }}
           >
             {trail.title}
           </span>
         </button>
+        {emphasisCount > 0 && (
+          <span
+            title={`${emphasisCount} emphasized step${emphasisCount === 1 ? '' : 's'}`}
+            style={{
+              display: 'inline-flex',
+              alignItems: 'center',
+              gap: 2,
+              flexShrink: 0,
+              marginRight: 4,
+              fontSize: theme.fontSizes[0],
+              fontFamily: theme.fonts.monospace,
+              color: theme.colors.accent ?? theme.colors.primary ?? muted,
+            }}
+          >
+            <Star size={11} strokeWidth={2} fill="currentColor" />
+            {emphasisCount}
+          </span>
+        )}
         {!collapsed && (
           <>
           {onToggleLayoutFocus && trail.steps.length > 0 && (
@@ -466,11 +504,22 @@ function TrailFlow({
         >
           {trail.steps.map((step, i) => {
             const stepActive = active !== null && active.stepIndex === i;
-            const proposed = stepProposed(step);
             const revealed =
               stepActive || hoveredStep === i || focusedStep === i || copiedStep === i;
             const copied = copiedStep === i;
             const copyHovered = copyHoverStep === i;
+            const record = stepEmphasis?.get(emphasisKey(trail.id, step));
+            const display = trailStepDisplay(step, componentByAlias);
+            // Calls nest; uses/data steps sit at their anchor frame's depth.
+            const stackDepth = buildTrailStack(
+              trail,
+              i,
+              componentByAlias,
+            ).frames.length;
+            // The guidance body follows step focus: clicking a step opens it,
+            // clicking the focused step again returns to the flow. Hover is
+            // deliberately not enough — the list would flutter on sweep.
+            const guidanceVisible = focusedStepIndex === i && !!record?.guidance;
             return (
               <div
                 key={`${trailStepGraphEdgeId(step)}-${i}`}
@@ -482,12 +531,16 @@ function TrailFlow({
                   }
                 }}
               >
+                {/* The row's absolute affordances (star, copy) are scoped to
+                    this wrapper so the guidance body below cannot stretch
+                    them — `top:0;bottom:0` on the outer row would grow their
+                    hit area with the markdown block. */}
+                <div style={{ position: 'relative' }}>
                 <button
                   ref={(el) => {
                     stepButtonRefs.current[i] = el;
                   }}
                   type="button"
-                  title={proposed ? 'Step touches a proposed component' : undefined}
                   onMouseEnter={() => {
                     setHoveredStep(i);
                     scheduleHoverPreview(() => onHoverStep(trail, i));
@@ -495,11 +548,13 @@ function TrailFlow({
                   onClick={() => onFocusStep(trail, i)}
                   style={{
                     display: 'flex',
-                    alignItems: 'center',
+                    alignItems: 'flex-start',
                     gap: 8,
                     minWidth: 0,
                     width: '100%',
-                    padding: '8px 36px 8px 17px',
+                    padding: `8px 70px 8px ${
+                      17 + Math.max(0, stackDepth - 1) * 10
+                    }px`,
                     textAlign: 'left',
                     borderRadius: 0,
                     border: 'none',
@@ -513,11 +568,12 @@ function TrailFlow({
                     style={{
                       flexShrink: 0,
                       width: 14,
+                      paddingTop: 1,
                       fontSize: theme.fontSizes[0],
                       fontFamily: theme.fonts.monospace,
-                      fontWeight: proposed ? 700 : undefined,
-                      color: proposed
-                        ? PROPOSED_COLOR
+                      fontWeight: record ? 700 : undefined,
+                      color: record
+                        ? EMPHASIS_COLOR
                         : stepActive
                           ? theme.colors.text
                           : muted,
@@ -529,17 +585,39 @@ function TrailFlow({
                     style={{
                       flex: 1,
                       minWidth: 0,
-                      overflow: 'hidden',
-                      textOverflow: 'ellipsis',
-                      whiteSpace: 'nowrap',
+                      overflowWrap: 'anywhere',
+                      whiteSpace: 'normal',
                       fontSize: theme.fontSizes[1],
                       fontFamily: theme.fonts.monospace,
-                      color: proposed ? PROPOSED_COLOR : theme.colors.text,
+                      color: record
+                        ? EMPHASIS_COLOR
+                        : theme.colors.text,
                     }}
                   >
-                    {step.symbol}
+                    {display.primary}
                   </span>
                 </button>
+                {record && (
+                  <span
+                    aria-hidden
+                    title="Key step"
+                    style={{
+                      position: 'absolute',
+                      right: 34,
+                      top: 0,
+                      bottom: 0,
+                      display: 'inline-flex',
+                      alignItems: 'center',
+                      justifyContent: 'center',
+                      width: 'auto',
+                      aspectRatio: '1 / 1',
+                      pointerEvents: 'none',
+                      color: EMPHASIS_COLOR,
+                    }}
+                  >
+                    <Star size={12} strokeWidth={2} fill={EMPHASIS_COLOR} />
+                  </span>
+                )}
                 {revealed && (
                   <button
                     type="button"
@@ -581,6 +659,49 @@ function TrailFlow({
                     )}
                   </button>
                 )}
+                </div>
+                {guidanceVisible && record?.guidance && (
+                  <div
+                    style={{
+                      // Align with the step text: 17px row inset + 14px number
+                      // column + 8px gap.
+                      padding: '2px 12px 10px 39px',
+                      fontSize: theme.fontSizes[0],
+                      lineHeight: 1.5,
+                    }}
+                  >
+                    <IndustryMarkdownSlide
+                      content={record.guidance}
+                      slideIdPrefix={`step-guidance-${trail.id}-${i}`}
+                      slideIndex={0}
+                      isVisible={true}
+                      theme={theme}
+                      disableScroll={true}
+                      disableBasePadding
+                      enableKeyboardScrolling={false}
+                      autoFocusOnVisible={false}
+                    />
+                    {onRemoveStepEmphasis && (
+                      <button
+                        type="button"
+                        onClick={() => onRemoveStepEmphasis(trail, i)}
+                        style={{
+                          marginTop: 6,
+                          padding: 0,
+                          border: 'none',
+                          background: 'transparent',
+                          color: muted,
+                          fontFamily: theme.fonts.monospace,
+                          fontSize: theme.fontSizes[0],
+                          textDecoration: 'underline',
+                          cursor: 'pointer',
+                        }}
+                      >
+                        Remove guidance
+                      </button>
+                    )}
+                  </div>
+                )}
               </div>
             );
           })}
@@ -614,12 +735,6 @@ export interface TrailsPanelProps {
    * for a read-only panel.
    */
   onReorder?: (next: SubsystemTrail[]) => void;
-  /**
-   * Aliases of components marked `proposed`. A row whose steps touch one gets
-   * its title tinted, and each such step (index and title) is tinted too
-   * (darkgoldenrod, same as the proposed node treatment).
-   */
-  proposedAliases?: ReadonlySet<string>;
   /** Trail whose components are the only ones laid out on the canvas, if any. */
   layoutFocusedTrailId?: string | null;
   /**
@@ -627,6 +742,12 @@ export interface TrailsPanelProps {
    * flow's components and edges. Omit to hide the per-row focus control.
    */
   onFocusLayout?: (trailId: string) => void;
+  /** Host-owned step emphasis augmentations, keyed by trail + claim fingerprint. */
+  stepEmphasis?: StepEmphasisMap;
+  /** Toggle a step's guidance off. Omit to hide the remove action. */
+  onRemoveStepEmphasis?: (tl: SubsystemTrail, stepIndex: number) => void;
+  /** Alias → component, for turning hops into human display names. */
+  componentByAlias?: TrailComponentLabels;
 }
 
 /**
@@ -648,9 +769,11 @@ export function TrailsPanel({
   onHoverFlow,
   onLeaveStep,
   onReorder,
-  proposedAliases,
   layoutFocusedTrailId,
   onFocusLayout,
+  stepEmphasis,
+  onRemoveStepEmphasis,
+  componentByAlias,
 }: TrailsPanelProps) {
   const { theme } = useTheme();
   // Reordering is offered only while every row is collapsed: the compact list
@@ -811,6 +934,7 @@ export function TrailsPanel({
                     ? { stepIndex: hoveredTrailStep.stepIndex }
                     : null
               }
+              focusedStepIndex={focusedTrailId === tl.id ? focusedStepIndex : null}
               onToggleCollapsed={onToggleCollapsed}
               onFocusFlow={onFocusFlow}
               onClearFocus={onClearFocus}
@@ -830,11 +954,13 @@ export function TrailsPanel({
               }
               dragActive={dragIndex != null}
               isHoverSuppressed={isHoverSuppressed}
-              proposedAliases={proposedAliases}
+              componentByAlias={componentByAlias}
               layoutFocused={layoutFocusedTrailId === tl.id}
               onToggleLayoutFocus={
                 onFocusLayout ? (t) => onFocusLayout(t.id) : undefined
               }
+              stepEmphasis={stepEmphasis}
+              onRemoveStepEmphasis={onRemoveStepEmphasis}
             />
           </div>
         );