finos · jpgough-ms · Sep 8, 2026 · Sep 9, 2026 · Sep 9, 2026 · Sep 9, 2026
@@ -0,0 +1,36 @@
+import { render, screen } from '@testing-library/react';
+import { describe, expect, it } from 'vitest';
+import { TimelineHeader } from './TimelineHeader.js';
+
+describe('TimelineHeader', () => {
+    it('prepends "v" for semver versions', () => {
+        render(<TimelineHeader currentVersion="1.5.0" />);
+        const pill = screen.getByTestId('timeline-version-pill');
+        expect(pill).toHaveTextContent('v1.5.0');
+    });
+
+    it('does not prepend "v" for commit SHAs', () => {
+        render(<TimelineHeader currentVersion="cb7686e" />);
+        const pill = screen.getByTestId('timeline-version-pill');
+        expect(pill).toHaveTextContent('cb7686e');
+        expect(pill.textContent).not.toMatch(/^v/);
+    });
+
+    it('does not prepend "v" for full-length commit SHAs', () => {
+        render(<TimelineHeader currentVersion="e46b2d5a1f3c9d8b7e2a0f4c6d8e1b3a5c7d9f0e" />);
+        const pill = screen.getByTestId('timeline-version-pill');
+        expect(pill.textContent).not.toMatch(/^v/);
+    });
+
+    it('prepends "v" for versions with non-hex characters', () => {
+        render(<TimelineHeader currentVersion="2.0.0-beta" />);
+        const pill = screen.getByTestId('timeline-version-pill');
+        expect(pill).toHaveTextContent('v2.0.0-beta');
+    });
+
+    it('sets the title attribute with the raw version', () => {
+        render(<TimelineHeader currentVersion="cb7686e" />);
+        const pill = screen.getByTestId('timeline-version-pill');
+        expect(pill).toHaveAttribute('title', 'Viewing version cb7686e');
+    });
+});
@@ -18,7 +18,10 @@ interface TimelineHeaderProps {
  * explanatory copy makes it obvious that clicking a moment re-renders both the
  * Diagram and JSON views.
  */
+const isCommitSha = (v: string) => /^[0-9a-f]{5,40}$/.test(v);
+
 export function TimelineHeader({ currentVersion, children }: TimelineHeaderProps) {
+    const displayVersion = isCommitSha(currentVersion) ? currentVersion : `v${currentVersion}`;
     return (
         <div className="flex items-center gap-2 shrink-0" style={{ paddingTop: 4 }}>
             <IoTimeOutline size={14} style={{ color: colors.ink[500], strokeWidth: 2 }} />
@@ -46,7 +49,7 @@ export function TimelineHeader({ currentVersion, children }: TimelineHeaderProps
                 }}
                 title={`Viewing version ${currentVersion}`}
             >
-                v{currentVersion}
+                {displayVersion}
             </span>
             {children}
         </div>

@@ -211,4 +211,58 @@ describe('DocumentDetailSection', () => {
         expect(mockFetchVersionsByCustomId).toHaveBeenCalledWith('test-ns', 'my-payment-standard', 'Standards');
         expect(mockFetchStandardVersions).not.toHaveBeenCalled();
     });
+
+    it('renders markdown content when data is a markdown string', () => {
+        const data: Data = {
+            id: 'std-123',
+            version: 'latest',
+            name: 'test-ns',
+            calmType: 'Standards',
+            data: '# TLS Policy\n\nAll services must use TLS 1.2+.',
+        };
+
+        render(
+            <MemoryRouter>
+                <DocumentDetailSection data={data} />
+            </MemoryRouter>
+        );
+
+        expect(screen.getByText('All services must use TLS 1.2+.')).toBeInTheDocument();
+    });
+
+    it('shows display name from markdown heading in breadcrumb', () => {
+        const data: Data = {
+            id: '12345',
+            version: 'latest',
+            name: 'test-ns',
+            calmType: 'Standards',
+            data: '# My Standard Name\n\nContent.',
+        };
+
+        const { container } = render(
+            <MemoryRouter>
+                <DocumentDetailSection data={data} />
+            </MemoryRouter>
+        );
+
+        expect(container.textContent).toContain('My Standard Name');
+    });
+
+    it('shows type label in breadcrumb', () => {
+        const data: Data = {
+            id: 'std-1',
+            version: 'latest',
+            name: 'fae-calm',
+            calmType: 'Standards',
+            data: '# Test\n\nBody.',
+        };
+
+        const { container } = render(
+            <MemoryRouter>
+                <DocumentDetailSection data={data} />
+            </MemoryRouter>
+        );
+
+        expect(container.textContent).toContain('Standards');
+    });
 });
@@ -1,6 +1,7 @@
 import { useEffect, useMemo, useState } from 'react';
 import { useNavigate } from 'react-router-dom';
 import { IoGridOutline, IoGitNetworkOutline } from 'react-icons/io5';
+import Markdown from 'react-markdown';
 import { Data, isSlug } from '../../../model/calm.js';
 import { CalmService } from '../../../service/calm-service.js';
 import { sortVersionsDescending } from '../../../model/version.js';
@@ -11,6 +12,24 @@ interface DocumentDetailSectionProps {
     data?: Data;
 }
 
+function getDisplayName(data: Data): string {
+    if (typeof data.data === 'string') {
+        const content = data.data as string;
+        const headingMatch = content.match(/^#\s+(.+)$/m);
+        if (headingMatch) return headingMatch[1];
+    }
+    if (typeof data.data === 'object' && data.data && 'name' in (data.data as object)) {
+        return String((data.data as Record<string, unknown>).name);
+    }
+    return data.id;
+}
+
+function isMarkdownContent(data: Data): boolean {
+    if (typeof data.data !== 'string') return false;
+    const content = data.data as string;
+    return content.startsWith('#') || content.startsWith('---') || !content.startsWith('{');
+}
+
 function calmTypeToUrlSegment(calmType: string): string {
     switch (calmType) {
         case 'Standards': return 'standards';
@@ -69,14 +88,22 @@ export function DocumentDetailSection({ data }: DocumentDetailSectionProps) {
                     icon={getIcon()}
                     namespace={data.name}
                     id={data.id}
+                    displayName={getDisplayName(data)}
+                    typeLabel={data.calmType}
                     version={data.version}
                     typeSegment={calmTypeToUrlSegment(data.calmType)}
                     versions={versions}
                     onVersionChange={handleVersionChange}
                 />
 
                 <div className="flex-1 min-h-0 overflow-auto bg-base-200">
-                    <JsonRenderer json={data} />
+                    {isMarkdownContent(data) ? (
+                        <div className="prose prose-sm max-w-none p-6 bg-base-100">
+                            <Markdown>{data.data as string}</Markdown>
+                        </div>
+                    ) : (
+                        <JsonRenderer json={data} />
+                    )}
                 </div>
             </div>
         </div>

@@ -95,9 +95,11 @@ export function ItemCard({
     const chip =
         meta !== undefined
             ? meta
-            : versionCount !== undefined
+            : versionCount !== undefined && versionCount > 0
               ? `${versionCount} ${versionCount === 1 ? 'version' : 'versions'}`
-              : customId;
+              : versionCount === 0
+                ? customId || undefined
+                : customId;
 
     return (
         <article

@@ -30,6 +30,18 @@ describe('sortVersionsDescending', () => {
         expect(result).toEqual(['2.0.0', '1.5.0', '1.0.0']);
         expect(input).toEqual(['1.0.0', '2.0.0', '1.5.0']);
     });
+
+    it('reverses SHA versions from chronological to newest-first', () => {
+        const input = ['abc1234', 'def5678', 'f1339ab'];
+        const result = sortVersionsDescending(input);
+        expect(result).toEqual(['f1339ab', 'def5678', 'abc1234']);
+    });
+
+    it('does not re-sort SHA versions alphabetically', () => {
+        const input = ['aaa1111', 'fff9999', 'bbb2222'];
+        const result = sortVersionsDescending(input);
+        expect(result).toEqual(['bbb2222', 'fff9999', 'aaa1111']);
+    });
 });
 
 describe('pickLatestVersion', () => {
@@ -44,4 +56,9 @@ describe('pickLatestVersion', () => {
     it('returns the only version when the list has one entry', () => {
         expect(pickLatestVersion(['3.4.5'])).toBe('3.4.5');
     });
+
+    it('returns the last SHA (newest) from chronological list', () => {
+        const input = ['abc1234', 'def5678', 'f1339ab'];
+        expect(pickLatestVersion(input)).toBe('f1339ab');
+    });
 });
@@ -33,8 +33,13 @@ export function compareVersions(a: string, b: string): number {
 
 /**
  * Return versions sorted newest-first.
+ * For commit SHAs, the backend returns chronological (oldest first) —
+ * reverse to get newest-first, matching semver sort behavior.
  */
 export function sortVersionsDescending(versions: string[]): string[] {
+    if (versions.length > 0 && /^[0-9a-f]{5,40}$/.test(versions[0])) {
+        return [...versions].reverse();
+    }
     return [...versions].sort((a, b) => compareVersions(b, a));
 }
 

@@ -5,8 +5,10 @@ import { DiagramActionsContext } from '../../context/DiagramActionsContext.js';
 import { restoreLocation, setHostname } from '../../../test-support/window-location.js';
 
 vi.mock('reactflow', () => ({
-    Handle: () => null,
-    Position: { Right: 'right', Left: 'left' },
+    Handle: ({ position, id }: { position: string; id: string }) => (
+        <div data-testid={`handle-${id}`} data-position={position} />
+    ),
+    Position: { Top: 'top', Right: 'right', Bottom: 'bottom', Left: 'left' },
 }));
 
 function makeNodeProps(details?: Record<string, unknown>) {
@@ -188,4 +190,43 @@ describe('CustomNode — external URL support', () => {
 
         expect(screen.getByTitle('Has detailed architecture')).toBeInTheDocument();
     });
+
+    it('renders handles on all four sides for edge connection', () => {
+        const props = makeNodeProps();
+        const { container } = renderNode(props);
+
+        expect(container.querySelector('[data-testid="handle-top-target"]')).not.toBeNull();
+        expect(container.querySelector('[data-testid="handle-bottom-source"]')).not.toBeNull();
+        expect(container.querySelector('[data-testid="handle-left-target"]')).not.toBeNull();
+        expect(container.querySelector('[data-testid="handle-right-source"]')).not.toBeNull();
+    });
+
+    it('applies building-block-style background and text colors from metadata', () => {
+        const props = {
+            id: 'node-styled',
+            type: 'custom',
+            selected: false,
+            zIndex: 0,
+            isConnectable: true,
+            xPos: 0,
+            yPos: 0,
+            dragging: false,
+            data: {
+                label: 'Styled Node',
+                description: 'A styled node',
+                'node-type': 'webclient',
+                metadata: {
+                    'building-block-style': {
+                        background: '#1C4587',
+                        text: '#ffffff',
+                    },
+                },
+            },
+        };
+
+        const { container } = renderNode(props);
+        const nodeDiv = container.querySelector('[data-testid="custom-node"] > div');
+        expect(nodeDiv).not.toBeNull();
+        expect(nodeDiv?.getAttribute('style')).toContain('rgb(28, 69, 135)');
+    });
 });
@@ -95,6 +95,9 @@ export function CustomNode({ data }: NodeProps) {
   const isUnknownArch = !!detailedArchitecture && archResolution.type === 'unknown';
   const archPath = isSameOriginArch ? archResolution.path : undefined;
 
+    // Extract building-block-style colors from metadata (if present)
+    const buildingBlockStyle = data.metadata?.['building-block-style'] as { background?: string; text?: string } | undefined;
+
     // Extract AIGF data (if present in node metadata)
     const aigf = data.metadata?.aigf;
     const riskLevel = aigf?.['risk-level'] || null;
@@ -169,21 +172,23 @@ export function CustomNode({ data }: NodeProps) {
       {/* Base node - always visible, fixed size */}
       <div
         style={{
-          background: THEME.colors.card,
-          border: `2px solid ${borderColor}`,
+          background: buildingBlockStyle?.background || `${nodeTypeStyle.color}12`,
+          border: `2px solid ${buildingBlockStyle?.background || borderColor}`,
           borderRadius: '12px',
           padding: '16px',
           width: '100%',
-          color: THEME.colors.foreground,
+          color: buildingBlockStyle?.text || THEME.colors.foreground,
           fontSize: '14px',
           fontWeight: 500,
           boxShadow: isHovered ? THEME.shadows.lg : THEME.shadows.sm,
           transition: 'box-shadow 0.3s ease-in-out',
         }}
       >
       {/* Hidden handles to satisfy React Flow; floating edge computes actual attachment */}
-      <Handle type="source" position={Position.Right} id="source" style={{ opacity: 0 }} />
-      <Handle type="target" position={Position.Left} id="target" style={{ opacity: 0 }} />
+      <Handle type="target" position={Position.Top} id="top-target" style={{ opacity: 0 }} />
+      <Handle type="source" position={Position.Bottom} id="bottom-source" style={{ opacity: 0 }} />
+      <Handle type="target" position={Position.Left} id="left-target" style={{ opacity: 0 }} />
+      <Handle type="source" position={Position.Right} id="right-source" style={{ opacity: 0 }} />
 
       <div style={{ display: 'flex', alignItems: 'flex-start', justifyContent: 'space-between', gap: '8px' }}>
         <div style={{ fontWeight: 600, marginBottom: '4px', flex: 1, display: 'flex', alignItems: 'center', gap: '8px' }}>