@bluefly/openstandardagents 0.2.4 → 0.2.5-RC

package/website/components/docs/DocsSidebar.tsx

@@ -2,7 +2,7 @@
 
 import Link from 'next/link';
 import { usePathname } from 'next/navigation';
-import { useState } from 'react';
+import { useState, useEffect } from 'react';
 import { DocsSearch } from './DocsSearch';
 import { VersionSelector } from './VersionSelector';
 
@@ -36,6 +36,13 @@ const navigation = [
       { href: '/docs/migration-guides/drupal-eca-to-ossa', label: 'Drupal ECA to OSSA' },
     ],
   },
+  {
+    title: 'Ecosystem',
+    items: [
+      { href: '/docs/ecosystem/overview', label: 'Ecosystem Overview' },
+      { href: '/docs/ecosystem/framework-support', label: 'Framework Support' },
+    ],
+  },
   {
     title: 'Reference',
     items: [
@@ -55,7 +62,37 @@ const navigation = [
 
 export function DocsSidebar() {
   const pathname = usePathname();
-  const [openSections, setOpenSections] = useState<string[]>(['Getting Started']);
+
+  // Calculate initial open sections based on pathname to avoid hydration mismatch
+  const getInitialOpenSections = (): string[] => {
+    const sections: string[] = ['Getting Started'];
+    const currentSection = navigation.find((section) =>
+      section.items.some((item) => item.href === pathname)
+    );
+    if (currentSection && !sections.includes(currentSection.title)) {
+      sections.push(currentSection.title);
+    }
+    return sections;
+  };
+
+  const [openSections, setOpenSections] = useState<string[]>(getInitialOpenSections);
+
+  // Update open sections when pathname changes (for client-side navigation)
+  useEffect(() => {
+    const currentSection = navigation.find((section) =>
+      section.items.some((item) => item.href === pathname)
+    );
+
+    if (currentSection) {
+      setOpenSections((prev) => {
+        // Only add if not already in the array
+        if (!prev.includes(currentSection.title)) {
+          return [...prev, currentSection.title];
+        }
+        return prev;
+      });
+    }
+  }, [pathname]);
 
   const toggleSection = (title: string): void => {
     setOpenSections((prev) =>
@@ -68,7 +105,7 @@ export function DocsSidebar() {
   return (
     <aside className="w-64 bg-gray-100 border-r border-gray-300 p-4 overflow-y-auto h-screen sticky top-0">
       <nav>
-        <Link href="/docs" className="block mb-6 font-semibold text-primary hover:text-primary-dark">
+        <Link href="/docs" className="block mb-6 font-semibold text-primary hover:text-accent">
           Documentation
         </Link>
         <div className="mb-6">

package/website/components/docs/MarkdownContent.tsx

@@ -1,40 +1,192 @@
-import React from 'react';
+'use client';
+
+import React, { useEffect } from 'react';
 import ReactMarkdown from 'react-markdown';
 import { Prism as SyntaxHighlighter } from 'react-syntax-highlighter';
 import { vscDarkPlus } from 'react-syntax-highlighter/dist/cjs/styles/prism';
 import remarkGfm from 'remark-gfm';
+import Link from 'next/link';
+import { usePathname } from 'next/navigation';
 
 interface MarkdownContentProps {
   content: string;
+  currentPath?: string; // Current pathname for resolving relative links
+}
+
+// Helper function to generate ID from heading text
+function generateId(text: string): string {
+  // Extract ID from {#id} syntax if present
+  const idMatch = text.match(/\{#([^}]+)\}/);
+  if (idMatch) {
+    return idMatch[1];
+  }
+  // Otherwise generate from text
+  return text
+    .toString()
+    .toLowerCase()
+    .replace(/[^\w\s-]/g, '')
+    .replace(/\s+/g, '-')
+    .replace(/-+/g, '-')
+    .trim();
+}
+
+// Helper function to clean heading text (remove {#id} syntax)
+function cleanHeadingText(text: string): string {
+  return text.replace(/\s*\{#[^}]+\}\s*$/, '').trim();
+}
+
+// Helper function to fix markdown bold syntax with spaces
+function fixMarkdownBold(content: string): string {
+  // Fix patterns like "** text**" or "**text **" to "**text**"
+  // Also handle cases where ** is at the start of a line or after a heading
+  return content
+    // Fix "** text" patterns (space after opening **)
+    .replace(/\*\* +([^*]+?)\*\*/g, '**$1**')
+    // Fix "text **" patterns (space before closing **)
+    .replace(/\*\*([^*]+?) +\*\*/g, '**$1**')
+    // Fix "** text **" patterns (spaces on both sides)
+    .replace(/\*\* +([^*]+?) +\*\*/g, '**$1**');
+}
+
+// Helper function to resolve relative markdown links to Next.js routes
+function resolveMarkdownLink(href: string, currentPath: string): string {
+  // Already absolute or external
+  if (href.startsWith('/') || href.startsWith('http') || href.startsWith('#')) {
+    return href;
+  }
+
+  // Split anchor from path
+  const [pathPart, anchor] = href.split('#');
+  const anchorPart = anchor ? `#${anchor}` : '';
+
+  // Remove .md extension
+  let normalized = pathPart.replace(/\.md$/, '');
+
+  // Handle relative paths starting with ./
+  if (normalized.startsWith('./')) {
+    normalized = normalized.slice(2);
+  }
+
+  // Convert PascalCase/CamelCase to kebab-case
+  normalized = normalized
+    .replace(/([a-z])([A-Z])/g, '$1-$2') // Insert dash before capital letters
+    .toLowerCase()
+    .replace(/[^a-z0-9/-]/g, '-') // Replace non-alphanumeric with dash
+    .replace(/-+/g, '-') // Collapse multiple dashes
+    .replace(/^-|-$/g, ''); // Remove leading/trailing dashes
+
+  // If currentPath is provided, resolve relative to it
+  if (currentPath && !normalized.startsWith('/')) {
+    // Get the directory of the current page
+    const pathParts = currentPath.split('/').filter(Boolean);
+    // Remove the last part (current file) to get directory
+    const currentDir = pathParts.slice(0, -1);
+
+    // Handle parent directory references (../)
+    if (normalized.startsWith('../')) {
+      const upLevels = (normalized.match(/\.\.\//g) || []).length;
+      normalized = normalized.replace(/\.\.\//g, '');
+      const newDir = currentDir.slice(0, -upLevels);
+      return `/docs/${newDir.join('/')}/${normalized}${anchorPart}`;
+    }
+
+    // Same directory or subdirectory
+    if (currentDir.length > 0) {
+      return `/docs/${currentDir.join('/')}/${normalized}${anchorPart}`;
+    }
+    return `/docs/${normalized}${anchorPart}`;
+  }
+
+  // Default to /docs/ prefix if no current path
+  return `/docs/${normalized}${anchorPart}`;
 }
 
-export function MarkdownContent({ content }: MarkdownContentProps) {
+export function MarkdownContent({ content, currentPath }: MarkdownContentProps) {
+  const pathname = usePathname();
+  const basePath = currentPath || pathname;
+
+  // Handle anchor link scrolling on mount and hash changes
+  useEffect(() => {
+    const handleHashChange = () => {
+      const hash = window.location.hash.slice(1);
+      if (hash) {
+        setTimeout(() => {
+          const element = document.getElementById(hash);
+          if (element) {
+            element.scrollIntoView({ behavior: 'smooth', block: 'start' });
+            // Offset for sticky header
+            window.scrollBy(0, -80);
+          }
+        }, 100);
+      }
+    };
+
+    handleHashChange();
+    window.addEventListener('hashchange', handleHashChange);
+    return () => window.removeEventListener('hashchange', handleHashChange);
+  }, [pathname]);
+
+  // Fix markdown bold syntax issues
+  const fixedContent = fixMarkdownBold(content);
+
   return (
-    <div className="markdown-content">
+    <div className="markdown-content [&_pre_code]:bg-transparent [&_pre_code]:text-code-text">
       <ReactMarkdown
         remarkPlugins={[remarkGfm]}
         components={{
-          // Headings
-          h1: ({ children }) => (
-            <h1 className="text-3xl font-bold text-gray-900 mt-8 mb-4 pb-2 border-b border-gray-200">
-              {children}
-            </h1>
-          ),
-          h2: ({ children }) => (
-            <h2 className="text-2xl font-semibold text-gray-900 mt-8 mb-4">
-              {children}
-            </h2>
-          ),
-          h3: ({ children }) => (
-            <h3 className="text-xl font-semibold text-gray-900 mt-6 mb-3">
-              {children}
-            </h3>
-          ),
-          h4: ({ children }) => (
-            <h4 className="text-lg font-semibold text-gray-900 mt-4 mb-2">
-              {children}
-            </h4>
-          ),
+          // Headings with IDs
+          h1: ({ children }) => {
+            const text = React.Children.toArray(children).join('');
+            const id = generateId(text);
+            const cleanText = cleanHeadingText(text);
+            return (
+              <h1
+                id={id}
+                className="text-3xl md:text-4xl font-bold text-gray-900 mt-8 mb-4 pb-2 border-b border-gray-200 scroll-mt-20"
+              >
+                {cleanText}
+              </h1>
+            );
+          },
+          h2: ({ children }) => {
+            const text = React.Children.toArray(children).join('');
+            const id = generateId(text);
+            const cleanText = cleanHeadingText(text);
+            return (
+              <h2
+                id={id}
+                className="text-2xl md:text-3xl font-semibold text-gray-900 mt-8 mb-4 scroll-mt-20"
+              >
+                {cleanText}
+              </h2>
+            );
+          },
+          h3: ({ children }) => {
+            const text = React.Children.toArray(children).join('');
+            const id = generateId(text);
+            const cleanText = cleanHeadingText(text);
+            return (
+              <h3
+                id={id}
+                className="text-xl md:text-2xl font-semibold text-gray-900 mt-6 mb-3 scroll-mt-20"
+              >
+                {cleanText}
+              </h3>
+            );
+          },
+          h4: ({ children }) => {
+            const text = React.Children.toArray(children).join('');
+            const id = generateId(text);
+            const cleanText = cleanHeadingText(text);
+            return (
+              <h4
+                id={id}
+                className="text-lg md:text-xl font-semibold text-gray-900 mt-4 mb-2 scroll-mt-20"
+              >
+                {cleanText}
+              </h4>
+            );
+          },
 
           // Paragraphs
           p: ({ children }) => (
@@ -43,31 +195,75 @@ export function MarkdownContent({ content }: MarkdownContentProps) {
             </p>
           ),
 
-          // Links
-          a: ({ href, children }) => (
-            <a
-              href={href}
-              className="text-blue-600 hover:text-blue-800 underline"
-              target={href?.startsWith('http') ? '_blank' : undefined}
-              rel={href?.startsWith('http') ? 'noopener noreferrer' : undefined}
-            >
-              {children}
-            </a>
-          ),
+          // Links - handle anchor links and internal/external links
+          a: ({ href, children }) => {
+            if (!href) return <>{children}</>;
+
+            // Handle anchor links (starting with #)
+            if (href.startsWith('#')) {
+              return (
+                <a
+                  href={href}
+                  onClick={(e) => {
+                    e.preventDefault();
+                    const id = href.slice(1);
+                    const element = document.getElementById(id);
+                    if (element) {
+                      element.scrollIntoView({ behavior: 'smooth', block: 'start' });
+                      // Offset for sticky header
+                      window.scrollBy(0, -80);
+                      // Update URL without scrolling
+                      window.history.pushState(null, '', `${pathname}${href}`);
+                    }
+                  }}
+                  className="text-primary hover:text-accent underline"
+                >
+                  {children}
+                </a>
+              );
+            }
 
-          // Lists
+            // Handle external links
+            if (href.startsWith('http')) {
+              return (
+                <a
+                  href={href}
+                  className="text-primary hover:text-accent underline"
+                  target="_blank"
+                  rel="noopener noreferrer"
+                >
+                  {children}
+                </a>
+              );
+            }
+
+            // Resolve relative markdown links to Next.js routes
+            const resolvedHref = resolveMarkdownLink(href, basePath);
+
+            // Handle internal links
+            return (
+              <Link
+                href={resolvedHref}
+                className="text-primary hover:text-primary-dark underline"
+              >
+                {children}
+              </Link>
+            );
+          },
+
+          // Lists - Tighter spacing for technical documentation
           ul: ({ children }) => (
-            <ul className="list-disc list-inside mb-4 space-y-2 text-gray-700">
+            <ul className="list-disc list-outside mb-3 ml-5 space-y-1 text-gray-700 text-base">
               {children}
             </ul>
           ),
           ol: ({ children }) => (
-            <ol className="list-decimal list-inside mb-4 space-y-2 text-gray-700">
+            <ol className="list-decimal list-outside mb-3 ml-5 space-y-1 text-gray-700 text-base">
               {children}
             </ol>
           ),
           li: ({ children }) => (
-            <li className="leading-7">
+            <li className="leading-relaxed pl-1">
               {children}
             </li>
           ),
@@ -109,13 +305,16 @@ export function MarkdownContent({ content }: MarkdownContentProps) {
           ),
 
           // Code
-          code({ className, children }) {
+          code({ className, children, ...props }: any) {
             const match = /language-(\w+)/.exec(className || '');
             const isInline = !match;
 
+            // Check if this code is inside a pre tag (block code)
+            const isBlockCode = (props.node?.parent as any)?.tagName === 'pre';
+
             if (match) {
               return (
-                <div className="my-4 rounded-lg overflow-hidden">
+                <div className="my-4 rounded-lg overflow-hidden overflow-x-auto">
                   <SyntaxHighlighter
                     style={vscDarkPlus as any}
                     language={match[1]}
@@ -124,6 +323,8 @@ export function MarkdownContent({ content }: MarkdownContentProps) {
                       margin: 0,
                       borderRadius: '0.5rem',
                       fontSize: '0.875rem',
+                      backgroundColor: '#1e1e1e',
+                      color: '#d4d4d4',
                     }}
                   >
                     {String(children).replace(/\n$/, '')}
@@ -132,19 +333,36 @@ export function MarkdownContent({ content }: MarkdownContentProps) {
               );
             }
 
+            // If it's a block code (inside pre), use dark background - no light background
+            if (isBlockCode) {
+              return (
+                <code className="bg-transparent text-code-text text-sm font-mono whitespace-pre">
+                  {children}
+                </code>
+              );
+            }
+
+            // Inline code
             return (
-              <code className="bg-gray-100 text-red-600 px-1.5 py-0.5 rounded text-sm font-mono">
+              <code className="bg-gray-100 text-primary px-1.5 py-0.5 rounded text-sm font-mono">
                 {children}
               </code>
             );
           },
 
           // Pre (for code blocks without language)
-          pre: ({ children }) => (
-            <pre className="bg-gray-900 text-gray-100 p-4 rounded-lg overflow-x-auto my-4 text-sm">
-              {children}
-            </pre>
-          ),
+          pre: ({ children }) => {
+            // Check if children contain a code element
+            const hasCode = React.Children.toArray(children).some(
+              (child: any) => child?.type === 'code' || child?.props?.node?.tagName === 'code'
+            );
+
+            return (
+              <pre className="bg-code-bg text-code-text p-4 rounded-lg overflow-x-auto my-4 text-sm font-mono">
+                {children}
+              </pre>
+            );
+          },
 
           // Horizontal rule
           hr: () => (

package/website/components/docs/VersionSelector.tsx

@@ -2,15 +2,17 @@
 
 import { usePathname, useRouter } from 'next/navigation';
 import { useState } from 'react';
-import { OSSA_VERSION_TAG } from '@/lib/version';
-
-const versions = [
-  { value: OSSA_VERSION_TAG, label: `${OSSA_VERSION_TAG} (Current)`, default: true },
-  { value: 'v1.0', label: 'v1.0 (Coming Soon)', disabled: true },
-];
+import { 
+  STABLE_VERSION_TAG, 
+  DEV_VERSION_TAG, 
+  ALL_VERSIONS,
+  STABLE_VERSIONS,
+  DEV_VERSIONS,
+  getVersionInfo
+} from '@/lib/version';
 
 export function VersionSelector() {
-  const [selectedVersion, setSelectedVersion] = useState(OSSA_VERSION_TAG);
+  const [selectedVersion, setSelectedVersion] = useState(STABLE_VERSION_TAG);
   const router = useRouter();
   const pathname = usePathname();
 
@@ -20,6 +22,45 @@ export function VersionSelector() {
     // For now, we just update the UI
   };
 
+  // Build version options grouped by type
+  const versionOptions: Array<{ value: string; label: string; disabled: boolean; group?: string }> = [];
+  
+  // Add stable versions
+  if (STABLE_VERSIONS.length > 0) {
+    STABLE_VERSIONS.forEach((v) => {
+      const isLatest = v.version === STABLE_VERSION_TAG.replace('v', '');
+      versionOptions.push({
+        value: v.tag,
+        label: `${v.tag}${isLatest ? ' (Latest Stable)' : ''}${v.published ? '' : ' (Unpublished)'}`,
+        disabled: !v.available,
+        group: 'stable'
+      });
+    });
+  }
+  
+  // Add dev/pre-release versions
+  if (DEV_VERSIONS.length > 0) {
+    DEV_VERSIONS.forEach((v) => {
+      const isLatestDev = v.version === (DEV_VERSION_TAG?.replace('v', '') || '');
+      const typeLabel = v.type === 'dev' ? 'Dev' : 'Pre-release';
+      versionOptions.push({
+        value: v.tag,
+        label: `${v.tag} (${typeLabel}${isLatestDev ? ' - Latest' : ''})${v.published ? '' : ' - Unpublished'}`,
+        disabled: !v.available,
+        group: v.type
+      });
+    });
+  }
+  
+  // Fallback if no versions loaded
+  if (versionOptions.length === 0) {
+    versionOptions.push({
+      value: STABLE_VERSION_TAG,
+      label: `${STABLE_VERSION_TAG} (Current)`,
+      disabled: false
+    });
+  }
+
   return (
     <div className="mb-4">
       <label htmlFor="version-select" className="block text-sm font-medium text-gray-700 mb-2">
@@ -33,7 +74,7 @@ export function VersionSelector() {
         aria-label="Select OSSA version"
         aria-describedby="version-description"
       >
-        {versions.map((version) => (
+        {versionOptions.map((version) => (
           <option
             key={version.value}
             value={version.value}
@@ -43,6 +84,21 @@ export function VersionSelector() {
           </option>
         ))}
       </select>
+      <p id="version-description" className="mt-1 text-sm text-gray-500">
+        {(() => {
+          const info = getVersionInfo(selectedVersion.replace('v', ''));
+          if (info) {
+            if (info.type === 'stable') {
+              return 'Stable release - recommended for production';
+            } else if (info.type === 'dev') {
+              return 'Development version - may contain breaking changes';
+            } else {
+              return 'Pre-release version - use with caution';
+            }
+          }
+          return 'Select a version to view documentation';
+        })()}
+      </p>
     </div>
   );
 }

package/website/components/examples/ExamplesViewer.tsx

@@ -179,7 +179,7 @@ export function ExamplesViewer({ examples }: ExamplesViewerProps) {
                 onClick={() => handleSelectExample(example)}
                 className={`w-full text-left px-4 py-3 rounded-lg text-sm transition-all border-2 ${
                   selectedExample?.path === example.path
-                    ? 'bg-gradient-to-r from-primary to-primary-dark text-white border-primary shadow-md'
+                    ? 'bg-gradient-to-r from-secondary via-primary to-accent text-white border-primary shadow-md'
                     : 'bg-white border-gray-200 hover:border-primary/50 hover:shadow-md'
                 }`}
               >
@@ -231,7 +231,7 @@ export function ExamplesViewer({ examples }: ExamplesViewerProps) {
               </div>
               <button
                 onClick={() => copyToClipboard(selectedExample.content)}
-                className="bg-gradient-to-r from-primary to-primary-dark text-white px-6 py-3 rounded-lg font-medium hover:shadow-lg transition-all flex items-center gap-2"
+                className="bg-gradient-to-r from-secondary via-primary to-accent text-white px-6 py-3 rounded-lg font-medium hover:shadow-lg transition-all flex items-center gap-2"
                 aria-label="Copy example code to clipboard"
                 title="Copy code"
               >

package/website/components/layout/Footer.tsx

@@ -8,7 +8,7 @@ export function Footer() {
           <div>
             <h3 className="text-white font-semibold mb-4">Open Standard Agents</h3>
             <p className="text-sm">
-              Industry Standard for Agent Orchestration. The vendor-neutral specification for multi-agent systems.
+              OSSA is an Open Standard for AI Agents. The vendor-neutral specification was created by Thomas Scola, founder of Bluefly.io.
             </p>
           </div>
           <div>
@@ -49,6 +49,11 @@ export function Footer() {
                   Blog
                 </Link>
               </li>
+              <li>
+                <Link href="/design-guide" className="hover:text-white transition-colors">
+                  Design Guide
+                </Link>
+              </li>
             </ul>
           </div>
           <div>