specra 0.2.2 → 0.2.4

package/config/specra.config.schema.json

@@ -45,31 +45,26 @@
     },
     "BannerConfig": {
       "additionalProperties": false,
-      "description": "Site-wide banner configuration",
+      "description": "Banner configuration for version-level or site-level banners.   Site-wide banner configuration",
       "properties": {
-        "dismissible": {
-          "description": "Whether the banner can be dismissed",
-          "type": "boolean"
-        },
-        "enabled": {
-          "description": "Whether the banner is enabled",
-          "type": "boolean"
-        },
-        "message": {
-          "description": "Banner message",
+        "text": {
+          "description": "Banner message text. Supports markdown links like [text](/url).",
           "type": "string"
         },
         "type": {
-          "description": "Banner type",
+          "description": "Banner style: info, warning, error, success   Banner type",
           "enum": [
             "info",
             "warning",
-            "success",
-            "error"
+            "error",
+            "success"
           ],
           "type": "string"
         }
       },
+      "required": [
+        "text"
+      ],
       "type": "object"
     },
     "DeploymentConfig": {

package/dist/components/docs/Callout.svelte

@@ -1,6 +1,7 @@
 <script lang="ts">
   import {
     Info,
+    PenLine,
     AlertTriangle,
     CheckCircle2,
     XCircle,
@@ -33,10 +34,10 @@
       defaultTitle: 'Info',
     },
     note: {
-      icon: Info,
-      className: 'bg-blue-500/10 border-blue-500/30 text-blue-900 dark:bg-blue-400/5 dark:border-blue-500/20 dark:text-blue-400',
-      iconClassName: 'text-blue-600 dark:text-blue-400',
-      titleClassName: 'text-blue-700 dark:text-blue-300',
+      icon: PenLine,
+      className: 'bg-slate-500/10 border-slate-500/30 text-slate-900 dark:bg-slate-400/5 dark:border-slate-400/20 dark:text-slate-300',
+      iconClassName: 'text-slate-600 dark:text-slate-400',
+      titleClassName: 'text-slate-700 dark:text-slate-300',
       defaultTitle: 'Note',
     },
     warning: {

package/dist/components/docs/CodeBlock.svelte

@@ -114,8 +114,8 @@
   </div>
 
   <!-- Code content -->
-  <div class="bg-gray-200/50 dark:bg-[#0d1117] rounded-b-xl overflow-x-auto border border-border/50">
-    <pre class="p-2 text-[13px] font-mono leading-relaxed text-gray-800 dark:text-gray-200"><code class="table w-full">{#each lines as line, i}{@const isDeletion = line.startsWith('-')}{@const isAddition = line.startsWith('+')}{@const isDiff = isDeletion || isAddition}{@const diffBgClass = isDeletion ? 'bg-red-500/5 dark:bg-red-500/10' : isAddition ? 'bg-green-500/5 dark:bg-green-500/10' : ''}{@const diffMarkerClass = isDeletion ? 'text-red-600 dark:text-red-400' : isAddition ? 'text-green-600 dark:text-green-400' : ''}{@const tokens = tokenizeLine(line)}<div class="table-row {diffBgClass}"><span class="table-cell pr-4 text-right select-none text-muted-foreground/40 w-8 align-top">{i + 1}</span><span class="table-cell align-top">{#if tokens.length === 0}&nbsp;{:else}{#each tokens as token, j}{#if j === 0 && isDiff && token.value.length > 0 && (token.value[0] === '+' || token.value[0] === '-')}<span class="{diffMarkerClass} font-bold">{token.value[0]}</span>{#if token.value.length > 1}<span class="token-{token.type}">{token.value.slice(1)}</span>{/if}{:else}<span class="token-{token.type}">{token.value}</span>{/if}{/each}{/if}</span></div>{/each}</code></pre>
+  <div class="bg-muted/30 dark:bg-muted/20 rounded-b-xl overflow-x-auto border border-border/50">
+    <pre class="p-2 text-[13px] font-mono leading-relaxed text-gray-800 dark:text-gray-200"><code class="table w-full">{#each lines as line, i}{@const isDeletion = language === 'diff' && line.startsWith('-') && !line.startsWith('--')}{@const isAddition = language === 'diff' && line.startsWith('+') && !line.startsWith('++')}{@const isDiff = isDeletion || isAddition}{@const diffBgClass = isDeletion ? 'bg-red-500/5 dark:bg-red-500/10' : isAddition ? 'bg-green-500/5 dark:bg-green-500/10' : ''}{@const diffMarkerClass = isDeletion ? 'text-red-600 dark:text-red-400' : isAddition ? 'text-green-600 dark:text-green-400' : ''}{@const tokens = tokenizeLine(line)}<div class="table-row {diffBgClass}"><span class="table-cell pr-4 text-right select-none text-muted-foreground/40 w-8 align-top">{i + 1}</span><span class="table-cell align-top">{#if tokens.length === 0}&nbsp;{:else}{#each tokens as token, j}{#if j === 0 && isDiff && token.value.length > 0 && (token.value[0] === '+' || token.value[0] === '-')}<span class="{diffMarkerClass} font-bold">{token.value[0]}</span>{#if token.value.length > 1}<span class="token-{token.type}">{token.value.slice(1)}</span>{/if}{:else}<span class="token-{token.type}">{token.value}</span>{/if}{/each}{/if}</span></div>{/each}</code></pre>
   </div>
 </div>
 

package/dist/components/docs/DocLayout.svelte

@@ -66,7 +66,7 @@
 
   <DocMetadata {meta} {config} />
 
-  <div class="prose prose-slate dark:prose-invert max-w-none prose-headings:scroll-mt-24 prose-headings:font-semibold prose-h1:text-4xl prose-h2:text-3xl prose-h2:mt-12 prose-h2:mb-4 prose-h3:text-2xl prose-h3:mt-8 prose-h3:mb-3 prose-p:text-base prose-p:leading-7 prose-p:text-muted-foreground prose-p:mb-4 prose-a:font-normal prose-a:transition-all prose-code:text-primary prose-code:bg-muted/50 prose-code:px-1.5 prose-code:py-0.5 prose-code:rounded-md prose-code:text-[13px] prose-code:font-mono prose-code:border prose-code:border-border/50 prose-code:before:content-none prose-code:after:content-none prose-pre:bg-transparent prose-pre:p-0 prose-ul:list-disc prose-ul:list-inside prose-ul:space-y-2 prose-ul:mb-4 prose-ol:list-decimal prose-ol:list-inside prose-ol:space-y-2 prose-ol:mb-4 prose-li:leading-7 prose-li:text-muted-foreground prose-strong:text-foreground prose-strong:font-semibold">
+  <div class="prose prose-slate dark:prose-invert max-w-none prose-headings:scroll-mt-24 prose-headings:font-semibold prose-h1:text-4xl prose-h2:text-3xl prose-h2:mt-12 prose-h2:mb-4 prose-h3:text-2xl prose-h3:mt-8 prose-h3:mb-3 prose-p:text-base prose-p:leading-7 prose-p:text-muted-foreground prose-p:mb-4 prose-a:font-normal prose-a:transition-all prose-code:text-primary prose-code:bg-muted/50 prose-code:px-1.5 prose-code:py-0.5 prose-code:rounded-md prose-code:text-[13px] prose-code:font-mono prose-code:border prose-code:border-border/50 prose-code:before:content-none prose-code:after:content-none prose-pre:bg-transparent prose-pre:p-0 prose-ul:list-disc prose-ul:space-y-2 prose-ul:mb-4 prose-ol:list-decimal prose-ol:space-y-2 prose-ol:mb-4 prose-li:leading-7 prose-li:text-muted-foreground [&_ul_ul]:ps-4 [&_ul_ul]:mt-2 [&_ul_ul]:mb-0 [&_ol_ol]:ps-4 [&_ol_ol]:mt-2 [&_ol_ol]:mb-0 [&_ol_ul]:ps-4 [&_ol_ul]:mt-2 [&_ol_ul]:mb-0 [&_ul_ol]:ps-4 [&_ul_ol]:mt-2 [&_ul_ol]:mb-0 prose-strong:text-foreground prose-strong:font-semibold">
     {@render children()}
   </div>
 

package/dist/components/docs/Header.svelte

@@ -3,23 +3,63 @@
   import { getConfigContext } from '../../stores/config.js';
   import { sidebarStore } from '../../stores/sidebar.js';
   import VersionSwitcher from './VersionSwitcher.svelte';
+  import VersionBanner from './VersionBanner.svelte';
   import ThemeToggle from './ThemeToggle.svelte';
   import SearchModal from './SearchModal.svelte';
   import Logo from './Logo.svelte';
+  import Icon from './Icon.svelte';
   import type { SpecraConfig } from '../../config.types.js';
+  import type { BannerConfig } from '../../config.types.js';
+  import type { Snippet } from 'svelte';
+  import { browser } from '$app/environment';
+
+  interface VersionMeta {
+    id: string;
+    label: string;
+    badge?: string;
+    hidden?: boolean;
+  }
 
   interface Props {
     currentVersion: string;
     versions: string[];
+    versionsMeta?: VersionMeta[];
+    versionBanner?: BannerConfig;
     config?: SpecraConfig;
+    subheader?: Snippet;
   }
 
-  let { currentVersion, versions, config: configProp }: Props = $props();
+  let { currentVersion, versions, versionsMeta, versionBanner, config: configProp, subheader }: Props = $props();
 
   const configStore = getConfigContext();
   let config = $derived(configProp || $configStore);
   let searchOpen = $state(false);
   let isFlush = $derived(config?.navigation?.sidebarStyle === 'flush');
+  let headerEl = $state<HTMLElement | null>(null);
+
+  // Set a CSS variable on :root with the header's actual height so sidebars
+  // can use it for their sticky top offset. Uses ResizeObserver to stay
+  // in sync when banner is dismissed or tabs change.
+  $effect(() => {
+    if (!browser || !headerEl) return;
+
+    function updateHeight() {
+      if (headerEl) {
+        const height = headerEl.offsetHeight;
+        document.documentElement.style.setProperty('--header-height', `${height}px`);
+      }
+    }
+
+    // Set immediately to avoid flash of wrong position
+    updateHeight();
+    // Also set on next frame in case layout hasn't settled
+    requestAnimationFrame(updateHeight);
+
+    const observer = new ResizeObserver(updateHeight);
+    observer.observe(headerEl);
+
+    return () => observer.disconnect();
+  });
 
   $effect(() => {
     const handleKeyDown = (e: KeyboardEvent) => {
@@ -33,7 +73,7 @@
   });
 </script>
 
-<header class="sticky top-0 z-50 w-full border-b border-border bg-background/95 backdrop-blur supports-backdrop-filter:bg-background/60">
+<header bind:this={headerEl} class="sticky top-0 z-50 w-full border-b border-border bg-background/95 backdrop-blur supports-backdrop-filter:bg-background/60">
   <div class="{isFlush ? '' : 'container mx-auto'} flex h-16 items-center justify-between px-4 md:px-6">
     <div class="flex items-center gap-1">
       <button
@@ -76,7 +116,7 @@
       {/if}
 
       {#if config.features?.versioning}
-        <VersionSwitcher {currentVersion} {versions} />
+        <VersionSwitcher {currentVersion} {versions} {versionsMeta} />
       {/if}
 
       <!-- Social Links -->
@@ -113,6 +153,28 @@
           <MessageCircle class="h-4 w-4" />
         </a>
       {/if}
+      {#if config.social?.custom}
+        {#each config.social.custom as link}
+          <span class="relative hidden md:inline-flex group/tip">
+            <a
+              href={link.url}
+              target="_blank"
+              rel="noopener noreferrer"
+              class="flex items-center justify-center h-9 w-9 rounded-md hover:bg-muted transition-colors"
+              aria-label={link.label}
+            >
+              {#if link.icon}
+                <Icon icon={link.icon} size={16} />
+              {:else}
+                <span class="text-xs font-medium">{link.label.slice(0, 2)}</span>
+              {/if}
+            </a>
+            <span class="absolute top-full left-1/2 -translate-x-1/2 mt-1 px-2 py-1 text-xs text-popover-foreground bg-popover border border-border rounded-md shadow-sm whitespace-nowrap pointer-events-none opacity-0 group-hover/tip:opacity-100 transition-opacity z-50">
+              {link.label}
+            </span>
+          </span>
+        {/each}
+      {/if}
 
       <ThemeToggle />
     </div>
@@ -120,4 +182,12 @@
 
   <!-- Search Modal -->
   <SearchModal isOpen={searchOpen} onClose={() => (searchOpen = false)} {config} />
+
+  {#if versionBanner}
+    <VersionBanner banner={versionBanner} />
+  {/if}
+
+  {#if subheader}
+    {@render subheader()}
+  {/if}
 </header>

package/dist/components/docs/Header.svelte.d.ts

@@ -1,8 +1,19 @@
 import type { SpecraConfig } from '../../config.types.js';
+import type { BannerConfig } from '../../config.types.js';
+import type { Snippet } from 'svelte';
+interface VersionMeta {
+    id: string;
+    label: string;
+    badge?: string;
+    hidden?: boolean;
+}
 interface Props {
     currentVersion: string;
     versions: string[];
+    versionsMeta?: VersionMeta[];
+    versionBanner?: BannerConfig;
     config?: SpecraConfig;
+    subheader?: Snippet;
 }
 declare const Header: import("svelte").Component<Props, {}, "">;
 type Header = ReturnType<typeof Header>;

package/dist/components/docs/MdxLayout.svelte

@@ -11,6 +11,6 @@
   let { children }: { children?: import('svelte').Snippet } = $props()
 </script>
 
-<div class="prose prose-slate dark:prose-invert max-w-none prose-headings:scroll-mt-24 prose-headings:font-semibold prose-h1:text-4xl prose-h2:text-3xl prose-h2:mt-12 prose-h2:mb-4 prose-h3:text-2xl prose-h3:mt-8 prose-h3:mb-3 prose-p:text-base prose-p:leading-7 prose-p:text-muted-foreground prose-p:mb-4 prose-a:font-normal prose-a:transition-all prose-code:text-primary prose-code:bg-muted/50 prose-code:px-1.5 prose-code:py-0.5 prose-code:rounded-md prose-code:text-[13px] prose-code:font-mono prose-code:border prose-code:border-border/50 prose-code:before:content-none prose-code:after:content-none prose-pre:bg-transparent prose-pre:p-0 prose-ul:list-disc prose-ul:list-inside prose-ul:space-y-2 prose-ul:mb-4 prose-ol:list-decimal prose-ol:list-inside prose-ol:space-y-2 prose-ol:mb-4 prose-li:leading-7 prose-li:text-muted-foreground prose-strong:text-foreground prose-strong:font-semibold">
+<div class="prose prose-slate dark:prose-invert max-w-none prose-headings:scroll-mt-24 prose-headings:font-semibold prose-h1:text-4xl prose-h2:text-3xl prose-h2:mt-12 prose-h2:mb-4 prose-h3:text-2xl prose-h3:mt-8 prose-h3:mb-3 prose-p:text-base prose-p:leading-7 prose-p:text-muted-foreground prose-p:mb-4 prose-a:font-normal prose-a:transition-all prose-code:text-primary prose-code:bg-muted/50 prose-code:px-1.5 prose-code:py-0.5 prose-code:rounded-md prose-code:text-[13px] prose-code:font-mono prose-code:border prose-code:border-border/50 prose-code:before:content-none prose-code:after:content-none prose-pre:bg-transparent prose-pre:p-0 prose-ul:list-disc prose-ul:space-y-2 prose-ul:mb-4 prose-ol:list-decimal prose-ol:space-y-2 prose-ol:mb-4 prose-li:leading-7 prose-li:text-muted-foreground [&_ul_ul]:ps-4 [&_ul_ul]:mt-2 [&_ul_ul]:mb-0 [&_ol_ol]:ps-4 [&_ol_ol]:mt-2 [&_ol_ol]:mb-0 [&_ol_ul]:ps-4 [&_ol_ul]:mt-2 [&_ol_ul]:mb-0 [&_ul_ol]:ps-4 [&_ul_ol]:mt-2 [&_ul_ol]:mb-0 prose-strong:text-foreground prose-strong:font-semibold">
   {@render children?.()}
 </div>

package/dist/components/docs/MobileDocLayout.svelte

@@ -56,24 +56,12 @@
 </script>
 
 <div class="min-h-screen bg-background">
-  <!-- Header -->
+  <!-- Header (includes banner and tab groups via subheader snippet) -->
   {@render header()}
 
   <!-- Site-wide Banner -->
   <SiteBanner {config} />
 
-  <!-- Tab Groups - shown only if configured -->
-  {#if config.navigation?.tabGroups && config.navigation.tabGroups.length > 0}
-    <TabGroups
-      tabGroups={config.navigation.tabGroups}
-      activeTabId={activeTabGroup}
-      onTabChange={handleTabChange}
-      flush={isFlush}
-      {docs}
-      {version}
-    />
-  {/if}
-
   <!-- Mobile Sidebar Overlay -->
   {#if sidebarOpen}
     <div
@@ -179,7 +167,7 @@
       </main>
     </div>
   {:else}
-    <main class="container mx-auto px-2 md:px-6 py-8">
+    <main class="container mx-auto px-2 md:px-6">
       <div class="flex">
         <!-- Desktop Sidebar - inside container -->
         <div class="hidden lg:block">
@@ -191,7 +179,7 @@
           />
         </div>
 
-        <div class="flex-1 min-w-0">
+        <div class="flex-1 min-w-0 py-4">
           <div class="flex flex-col gap-2 px-2 md:px-8">
             <!-- Content -->
             {@render children()}

package/dist/components/docs/Sidebar.svelte

@@ -33,24 +33,17 @@
 
   let { docs, version, onLinkClick, config, activeTabGroup }: Props = $props();
 
-  let hasTabGroups = $derived(
-    config.navigation?.tabGroups && config.navigation.tabGroups.length > 0
-  );
   let isFlush = $derived(config.navigation?.sidebarStyle === 'flush');
-  let stickyTop = $derived(hasTabGroups ? 'top-[7.5rem]' : 'top-24');
-  let maxHeight = $derived(
-    hasTabGroups ? 'max-h-[calc(100vh-10rem)]' : 'max-h-[calc(100vh-7rem)]'
-  );
   let containerClass = $derived(
     isFlush
-      ? `${maxHeight} overflow-y-auto p-4 border-r border-border`
-      : `${maxHeight} overflow-y-auto bg-muted/30 dark:bg-muted/10 rounded-2xl p-4 border border-border/50`
+      ? `overflow-y-auto p-4 border-r border-border`
+      : `overflow-y-auto bg-muted/30 dark:bg-muted/10 rounded-2xl p-4 border border-border/50`
   );
 </script>
 
 {#if config.navigation?.showSidebar}
-  <aside class="w-64 shrink-0 sticky {stickyTop} self-start">
-    <div class={containerClass}>
+  <aside class="w-64 shrink-0 sticky self-start pt-4" style="top: var(--header-height, 4rem);">
+    <div class={containerClass} style="max-height: calc(100vh - var(--header-height, 4rem) - 2rem);">
       <div class="flex items-center justify-between mb-4 px-2">
         <h2 class="text-xs font-semibold text-muted-foreground uppercase tracking-wider">Documentation</h2>
         {#if config.features?.showVersionBadge && version}

package/dist/components/docs/SidebarMenuItems.svelte

@@ -1,6 +1,6 @@
 <script lang="ts">
   import { page } from '$app/stores';
-  import { ChevronRight, ChevronDown, FolderOpen, Lock } from 'lucide-svelte';
+  import { ChevronRight, ChevronDown, Lock } from 'lucide-svelte';
   import type { SpecraConfig } from '../../config.types.js';
   import Icon from './Icon.svelte';
   import { sortSidebarItems, sortSidebarGroups } from '../../sidebar-utils.js';
@@ -260,8 +260,6 @@
       >
         {#if group.icon}
           <Icon icon={group.icon} size={16} className="shrink-0" />
-        {:else}
-          <FolderOpen size={16} class="shrink-0" />
         {/if}
         {group.label}
       </a>

package/dist/components/docs/Step.svelte

@@ -39,7 +39,7 @@
     font-size: 0.875rem;
     font-weight: 600;
     z-index: 10;
-    background: hsl(var(--primary));
-    color: hsl(var(--primary-foreground));
+    background: var(--primary);
+    color: var(--primary-foreground);
   }
 </style>

package/dist/components/docs/TabGroups.svelte

@@ -111,8 +111,8 @@
       {/if}
     </div>
   {:else}
-    <!-- Full version with sticky header -->
-    <div class="sticky top-16 z-30 border-b border-border bg-background/95 backdrop-blur supports-[backdrop-filter]:bg-background/60">
+    <!-- Full version -->
+    <div class="border-b border-border bg-muted/40 backdrop-blur supports-[backdrop-filter]:bg-muted/30">
       <div class="{flush ? '' : 'container mx-auto'} px-4 md:px-6">
         <!-- Mobile Dropdown -->
         <div class="md:hidden relative">

package/dist/components/docs/TableOfContents.svelte

@@ -16,14 +16,7 @@
   const maxDepth = $derived(config.navigation?.tocMaxDepth ?? 3);
   const filteredItems = $derived(items.filter((item) => item.level <= maxDepth));
 
-  // Check if tab groups are configured
-  const hasTabGroups = $derived(
-    config.navigation?.tabGroups != null && config.navigation.tabGroups.length > 0
-  );
-
-  // Adjust top position based on whether tabs are present
-  const stickyTop = $derived(hasTabGroups ? 'top-[7.5rem]' : 'top-24');
-  const maxHeight = $derived(hasTabGroups ? 'max-h-[calc(100vh-10rem)]' : 'max-h-[calc(100vh-7rem)]');
+  // Removed hardcoded top/max-height — now uses --header-height CSS variable set by Header
 
   $effect(() => {
     if (!browser || !showToc || filteredItems.length === 0) return;
@@ -79,8 +72,8 @@
 </script>
 
 {#if showToc && filteredItems.length > 0}
-  <aside class="w-64 hidden xl:block shrink-0 sticky {stickyTop} self-start">
-    <div class="{maxHeight} overflow-y-auto bg-muted/30 dark:bg-muted/10 rounded-2xl p-4 border border-border/50">
+  <aside class="w-64 hidden xl:block shrink-0 sticky self-start pt-4" style="top: var(--header-height, 4rem);">
+    <div class="overflow-y-auto bg-muted/30 dark:bg-muted/10 rounded-2xl p-4 border border-border/50" style="max-height: calc(100vh - var(--header-height, 4rem) - 2rem);">
       <h3 class="text-xs font-semibold text-muted-foreground uppercase tracking-wider mb-4 px-2">On this page</h3>
       <nav class="space-y-1">
         {#each filteredItems as item, index}

package/dist/components/docs/Timeline.svelte

@@ -0,0 +1,15 @@
+<script lang="ts">
+  import type { Snippet } from 'svelte';
+
+  interface Props {
+    children?: Snippet;
+  }
+
+  let { children }: Props = $props();
+</script>
+
+<div class="my-6 ml-4" style="counter-reset: timeline-step;">
+  {#if children}
+    {@render children()}
+  {/if}
+</div>

package/dist/components/docs/Timeline.svelte.d.ts

@@ -0,0 +1,7 @@
+import type { Snippet } from 'svelte';
+interface Props {
+    children?: Snippet;
+}
+declare const Timeline: import("svelte").Component<Props, {}, "">;
+type Timeline = ReturnType<typeof Timeline>;
+export default Timeline;

package/dist/components/docs/TimelineItem.svelte

@@ -0,0 +1,50 @@
+<script lang="ts">
+  import type { Snippet } from 'svelte';
+
+  interface Props {
+    title: string;
+    date?: string;
+    icon?: string;
+    children?: Snippet;
+  }
+
+  let { title, date, icon, children }: Props = $props();
+</script>
+
+<div class="timeline-item relative pl-8 pb-8 border-l-2 border-border last:border-l-0 last:pb-0">
+  <div class="mb-2">
+    <h3 class="text-lg font-semibold text-foreground">{title}</h3>
+    {#if date}
+      <span class="text-sm text-muted-foreground">{date}</span>
+    {/if}
+  </div>
+  <div class="prose prose-sm dark:prose-invert max-w-none [&>*:last-child]:mb-0">
+    {#if children}
+      {@render children()}
+    {/if}
+  </div>
+</div>
+
+<style>
+  .timeline-item {
+    counter-increment: timeline-step;
+  }
+  .timeline-item::before {
+    content: counter(timeline-step);
+    position: absolute;
+    top: 0;
+    left: -1px;
+    transform: translateX(-50%);
+    width: 2rem;
+    height: 2rem;
+    border-radius: 9999px;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    font-size: 0.875rem;
+    font-weight: 600;
+    z-index: 10;
+    background: var(--primary);
+    color: var(--primary-foreground);
+  }
+</style>

package/dist/components/docs/TimelineItem.svelte.d.ts

@@ -0,0 +1,10 @@
+import type { Snippet } from 'svelte';
+interface Props {
+    title: string;
+    date?: string;
+    icon?: string;
+    children?: Snippet;
+}
+declare const TimelineItem: import("svelte").Component<Props, {}, "">;
+type TimelineItem = ReturnType<typeof TimelineItem>;
+export default TimelineItem;

package/dist/components/docs/VersionBanner.svelte

@@ -0,0 +1,60 @@
+<script lang="ts">
+  import { Info, AlertTriangle, XCircle, CheckCircle2, X } from 'lucide-svelte';
+
+  interface BannerConfig {
+    text: string;
+    type?: 'info' | 'warning' | 'error' | 'success';
+  }
+
+  interface Props {
+    banner: BannerConfig;
+  }
+
+  let { banner }: Props = $props();
+
+  let dismissed = $state(false);
+
+  const styles = {
+    info: {
+      bg: 'bg-blue-500/10 border-blue-500/30',
+      text: 'text-blue-900 dark:text-blue-300',
+      icon: Info,
+    },
+    warning: {
+      bg: 'bg-yellow-500/10 border-yellow-500/30',
+      text: 'text-yellow-900 dark:text-yellow-300',
+      icon: AlertTriangle,
+    },
+    error: {
+      bg: 'bg-red-500/10 border-red-500/30',
+      text: 'text-red-900 dark:text-red-300',
+      icon: XCircle,
+    },
+    success: {
+      bg: 'bg-green-500/10 border-green-500/30',
+      text: 'text-green-900 dark:text-green-300',
+      icon: CheckCircle2,
+    },
+  };
+
+  let style = $derived(styles[banner.type || 'info']);
+  let IconComponent = $derived(style.icon);
+</script>
+
+{#if !dismissed}
+  <div class="border-b {style.bg} {style.text}">
+    <div class="max-w-7xl mx-auto px-4 py-2.5 flex items-center justify-between gap-3">
+      <div class="flex items-center gap-2 text-sm">
+        <IconComponent class="h-4 w-4 shrink-0" />
+        <span>{banner.text}</span>
+      </div>
+      <button
+        onclick={() => dismissed = true}
+        class="shrink-0 p-0.5 rounded hover:bg-black/10 dark:hover:bg-white/10 transition-colors"
+        aria-label="Dismiss banner"
+      >
+        <X class="h-3.5 w-3.5" />
+      </button>
+    </div>
+  </div>
+{/if}

package/dist/components/docs/VersionBanner.svelte.d.ts

@@ -0,0 +1,10 @@
+interface BannerConfig {
+    text: string;
+    type?: 'info' | 'warning' | 'error' | 'success';
+}
+interface Props {
+    banner: BannerConfig;
+}
+declare const VersionBanner: import("svelte").Component<Props, {}, "">;
+type VersionBanner = ReturnType<typeof VersionBanner>;
+export default VersionBanner;

package/dist/components/docs/VersionSwitcher.svelte

@@ -4,16 +4,38 @@
   import { page } from '$app/stores';
   import { browser } from '$app/environment';
 
+  interface VersionMeta {
+    id: string;
+    label: string;
+    badge?: string;
+    hidden?: boolean;
+  }
+
   interface Props {
     currentVersion: string;
     versions: string[];
+    versionsMeta?: VersionMeta[];
   }
 
-  let { currentVersion, versions }: Props = $props();
+  let { currentVersion, versions, versionsMeta }: Props = $props();
 
   let isOpen = $state(false);
   let dropdownEl = $state<HTMLDivElement | null>(null);
 
+  // Build version list: use metadata if available, filter hidden versions
+  let visibleVersions = $derived.by(() => {
+    if (versionsMeta && versionsMeta.length > 0) {
+      return versionsMeta.filter(v => !v.hidden);
+    }
+    return versions.map(id => ({ id, label: id }));
+  });
+
+  // Get current version display label
+  let currentLabel = $derived.by(() => {
+    const meta = versionsMeta?.find(v => v.id === currentVersion);
+    return meta?.label || currentVersion;
+  });
+
   $effect(() => {
     if (!browser || !isOpen) return;
 
@@ -38,8 +60,8 @@
     };
   });
 
-  function switchVersion(version: string) {
-    if (version === currentVersion) {
+  function switchVersion(versionId: string) {
+    if (versionId === currentVersion) {
       isOpen = false;
       return;
     }
@@ -47,7 +69,7 @@
     const currentPath = $page.url.pathname;
     const newPath = currentPath.replace(
       new RegExp(`/${currentVersion}(/|$)`),
-      `/${version}$1`
+      `/${versionId}$1`
     );
 
     isOpen = false;
@@ -55,7 +77,7 @@
   }
 </script>
 
-{#if versions.length > 1}
+{#if visibleVersions.length > 1}
   <div class="relative" bind:this={dropdownEl}>
     <button
       onclick={() => (isOpen = !isOpen)}
@@ -64,27 +86,32 @@
       aria-haspopup="listbox"
       aria-label="Switch version"
     >
-      <span>{currentVersion}</span>
+      <span>{currentLabel}</span>
       <ChevronDown class="h-3.5 w-3.5 text-muted-foreground transition-transform {isOpen ? 'rotate-180' : ''}" />
     </button>
 
     {#if isOpen}
       <div
-        class="absolute top-full right-0 mt-1 w-40 py-1 bg-popover border border-border rounded-md shadow-lg z-50"
+        class="absolute top-full right-0 mt-1 w-48 py-1 bg-popover border border-border rounded-md shadow-lg z-50"
         role="listbox"
         aria-label="Available versions"
       >
-        {#each versions as version}
+        {#each visibleVersions as version}
           <button
             role="option"
-            aria-selected={version === currentVersion}
-            onclick={() => switchVersion(version)}
-            class="w-full flex items-center justify-between px-3 py-1.5 text-sm transition-colors {version === currentVersion
+            aria-selected={version.id === currentVersion}
+            onclick={() => switchVersion(version.id)}
+            class="w-full flex items-center justify-between px-3 py-1.5 text-sm transition-colors {version.id === currentVersion
               ? 'text-primary bg-accent/50 font-medium'
               : 'text-foreground hover:bg-accent'}"
           >
-            <span>{version}</span>
-            {#if version === currentVersion}
+            <span class="flex items-center gap-2">
+              {version.label}
+              {#if version.badge}
+                <span class="px-1.5 py-0.5 text-[10px] font-medium rounded-full bg-primary/10 text-primary leading-none">{version.badge}</span>
+              {/if}
+            </span>
+            {#if version.id === currentVersion}
               <Check class="h-3.5 w-3.5 text-primary" />
             {/if}
           </button>