specra 0.2.5 → 0.2.7

package/dist/components/docs/SidebarMenuItems.svelte

@@ -42,12 +42,20 @@
   interface Props {
     docs: DocItem[];
     version: string;
+    product?: string;
     onLinkClick?: () => void;
     config: SpecraConfig;
     activeTabGroup?: string;
   }
 
-  let { docs, version, onLinkClick, config, activeTabGroup }: Props = $props();
+  let { docs = [], version, product, onLinkClick, config, activeTabGroup }: Props = $props();
+
+  /** URL prefix: /docs/{product}/{version} for named products, /docs/{version} for default */
+  let docsBase = $derived(
+    product && product !== '_default_'
+      ? `/docs/${product}/${version}`
+      : `/docs/${version}`
+  );
 
   let collapsed: Record<string, boolean> = $state({});
   let pathname = $derived($page.url.pathname.replace(/\/$/, ''));
@@ -176,14 +184,14 @@
 
   function isActiveInGroup(group: SidebarGroup): boolean {
     const hasActiveItem = group.items.some(
-      (doc) => pathname === `/docs/${version}/${doc.slug}`
+      (doc) => pathname === `${docsBase}/${doc.slug}`
     );
     if (hasActiveItem) return true;
     return Object.values(group.children).some((child) => isActiveInGroup(child));
   }
 
   function getGroupHref(group: SidebarGroup): string {
-    let groupHref = `/docs/${version}/${group.path}`;
+    let groupHref = `${docsBase}/${group.path}`;
 
     if (config.features?.i18n) {
       const i18n = config.features.i18n;
@@ -192,7 +200,7 @@
       const potentialLocale = pathParts[3];
 
       if (potentialLocale && locales.includes(potentialLocale)) {
-        groupHref = `/docs/${version}/${potentialLocale}/${group.path}`;
+        groupHref = `${docsBase}/${potentialLocale}/${group.path}`;
       }
     }
 
@@ -201,7 +209,7 @@
 
   function isGroupCollapsed(groupKey: string, group: SidebarGroup): boolean {
     const hasActive = isActiveInGroup(group);
-    const isGroupActive = pathname === `/docs/${version}/${group.path}`;
+    const isGroupActive = pathname === `${docsBase}/${group.path}`;
     if (hasActive || isGroupActive) return false;
     return collapsed[groupKey] ?? group.defaultCollapsed;
   }
@@ -240,7 +248,7 @@
   {@const hasChildren = sortedChildren.length > 0}
   {@const hasItems = sortedItems.length > 0}
   {@const hasContent = hasChildren || hasItems}
-  {@const isGroupActive = pathname === `/docs/${version}/${group.path}`}
+  {@const isGroupActive = pathname === `${docsBase}/${group.path}`}
   {@const isCollapsed = isGroupCollapsed(groupKey, group)}
   {@const marginLeft = depth > 0 ? 'ml-4' : ''}
   {@const groupHref = getGroupHref(group)}
@@ -289,7 +297,7 @@
           {#if item.type === 'group'}
             {@render renderGroup(`${groupKey}/${item.key}`, item.group, depth + 1)}
           {:else}
-            {@const href = `/docs/${version}/${item.doc.slug}`}
+            {@const href = `${docsBase}/${item.doc.slug}`}
             {@const isActive = pathname === href}
             <a
               {href}
@@ -316,7 +324,7 @@
 <nav class="space-y-1">
   {#if sortedStandalone.length > 0}
     {#each sortedStandalone as doc (doc.slug)}
-      {@const href = `/docs/${version}/${doc.slug}`}
+      {@const href = `${docsBase}/${doc.slug}`}
       {@const isActive = pathname === href}
       <a
         {href}

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

@@ -24,6 +24,7 @@ interface DocItem {
 interface Props {
     docs: DocItem[];
     version: string;
+    product?: string;
     onLinkClick?: () => void;
     config: SpecraConfig;
     activeTabGroup?: string;

package/dist/components/docs/TabGroups.svelte

@@ -24,10 +24,17 @@
     mobileOnly?: boolean;
     docs?: DocItem[];
     version?: string;
+    product?: string;
     flush?: boolean;
   }
 
-  let { tabGroups, activeTabId, onTabChange, mobileOnly = false, docs, version, flush = false }: Props = $props();
+  let { tabGroups, activeTabId, onTabChange, mobileOnly = false, docs, version, product, flush = false }: Props = $props();
+
+  let docsBase = $derived(
+    product && product !== '_default_' && version
+      ? `/docs/${product}/${version}`
+      : version ? `/docs/${version}` : '/docs'
+  );
 
   let dropdownOpen = $state(false);
 
@@ -58,7 +65,7 @@
       });
 
       if (firstDocInTab) {
-        goto(`/docs/${version}/${firstDocInTab.slug}`);
+        goto(`${docsBase}/${firstDocInTab.slug}`);
       }
     }
   }

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

@@ -18,6 +18,7 @@ interface Props {
     mobileOnly?: boolean;
     docs?: DocItem[];
     version?: string;
+    product?: string;
     flush?: boolean;
 }
 declare const TabGroups: import("svelte").Component<Props, {}, "">;

package/dist/components/docs/VersionSwitcher.svelte

@@ -27,7 +27,7 @@
     if (versionsMeta && versionsMeta.length > 0) {
       return versionsMeta.filter(v => !v.hidden);
     }
-    return versions.map(id => ({ id, label: id }));
+    return (versions ?? []).map(id => ({ id, label: id }));
   });
 
   // Get current version display label

package/dist/components/docs/index.d.ts

@@ -51,6 +51,7 @@ export { default as TimelineItem } from './TimelineItem.svelte';
 export { default as Tabs } from './Tabs.svelte';
 export { default as ThemeToggle } from './ThemeToggle.svelte';
 export { default as Tooltip } from './Tooltip.svelte';
+export { default as ProductSwitcher } from './ProductSwitcher.svelte';
 export { default as VersionBanner } from './VersionBanner.svelte';
 export { default as VersionSwitcher } from './VersionSwitcher.svelte';
 export { default as Video } from './Video.svelte';

package/dist/components/docs/index.js

@@ -52,6 +52,7 @@ export { default as TimelineItem } from './TimelineItem.svelte';
 export { default as Tabs } from './Tabs.svelte';
 export { default as ThemeToggle } from './ThemeToggle.svelte';
 export { default as Tooltip } from './Tooltip.svelte';
+export { default as ProductSwitcher } from './ProductSwitcher.svelte';
 export { default as VersionBanner } from './VersionBanner.svelte';
 export { default as VersionSwitcher } from './VersionSwitcher.svelte';
 export { default as Video } from './Video.svelte';

package/dist/components/ui/Button.svelte.d.ts

@@ -1,7 +1,7 @@
 import { type VariantProps } from 'class-variance-authority';
 export declare const buttonVariants: (props?: ({
     variant?: "link" | "default" | "destructive" | "outline" | "secondary" | "ghost" | null | undefined;
-    size?: "default" | "icon" | "sm" | "lg" | "icon-sm" | "icon-lg" | null | undefined;
+    size?: "icon" | "default" | "sm" | "lg" | "icon-sm" | "icon-lg" | null | undefined;
 } & import("class-variance-authority/types").ClassProp) | undefined) => string;
 export type ButtonVariants = VariantProps<typeof buttonVariants>;
 import type { HTMLButtonAttributes } from 'svelte/elements';

package/dist/config.d.ts

@@ -4,5 +4,5 @@
  * The actual config loading happens on the server and is passed as props
  */
 export { defaultConfig } from "./config.types";
-export type { SpecraConfig, VersionConfig, BannerConfig } from "./config.types";
+export type { SpecraConfig, VersionConfig, BannerConfig, ProductConfig, Product, DefaultProductConfig } from "./config.types";
 export { getConfig, getConfigValue, loadConfig, processContentWithEnv, replaceEnvVariables, validateConfig, reloadConfig, } from "./config.server";

package/dist/config.schema.json

@@ -74,6 +74,24 @@
         "hideLogo": {
           "type": "boolean",
           "description": "Whether to hide the site logo in the header"
+        },
+        "defaultProduct": {
+          "type": "object",
+          "description": "Configuration for the default product in multi-product mode. Falls back to site title and activeVersion if not set.",
+          "properties": {
+            "label": {
+              "type": "string",
+              "description": "Display name for the default product in the switcher"
+            },
+            "icon": {
+              "type": "string",
+              "description": "Icon for the default product (lucide icon name)"
+            },
+            "activeVersion": {
+              "type": "string",
+              "description": "Override active version for the default product"
+            }
+          }
         }
       }
     },

package/dist/config.server.d.ts

@@ -1,4 +1,4 @@
-import type { SpecraConfig, VersionConfig } from "./config.types";
+import type { SpecraConfig, VersionConfig, ProductConfig, Product } from "./config.types";
 /**
  * Load and parse the Specra configuration file
  * Falls back to default configuration if file doesn't exist or is invalid
@@ -41,13 +41,13 @@ export declare function getConfig(): SpecraConfig;
  * Reload the configuration (useful for development) (SERVER ONLY)
  */
 export declare function reloadConfig(userConfig: Partial<SpecraConfig>): SpecraConfig;
-export declare function loadVersionConfig(version: string): VersionConfig | null;
+export declare function loadVersionConfig(version: string, product?: string): VersionConfig | null;
 /**
- * Get the effective config for a specific version.
- * Merges global config with per-version overrides from _version_.json.
- * If no _version_.json exists, returns the global config unchanged.
+ * Get the effective config for a specific version and optional product.
+ * Merges in priority order: global ← product ← version.
+ * If no overrides exist, returns the global config unchanged.
  */
-export declare function getEffectiveConfig(version: string): SpecraConfig;
+export declare function getEffectiveConfig(version: string, product?: string): SpecraConfig;
 /**
  * Version metadata for display in the version switcher.
  */
@@ -67,7 +67,35 @@ export interface VersionMeta {
  * Get metadata for all versions, enriched with _version_.json data.
  * Hidden versions are included but marked — the UI decides whether to show them.
  */
-export declare function getVersionsMeta(versions: string[]): VersionMeta[];
+export declare function getVersionsMeta(versions: string[], product?: string): VersionMeta[];
+/**
+ * Load and parse a _product_.json file for a given product slug.
+ * Returns null if the file doesn't exist or is invalid.
+ */
+export declare function loadProductConfig(product: string): ProductConfig | null;
+/**
+ * Scan docs/ top-level directories for _product_.json files.
+ * Returns the full list of products including the default product.
+ *
+ * Detection logic:
+ * 1. Single readdir + stat calls — no recursive walks
+ * 2. If no _product_.json found → single-product mode (returns empty array)
+ * 3. If any found → multi-product mode; bare version folders become the default product
+ * 4. Product slugs that match version patterns (e.g., v1.0.0) are rejected with a clear error
+ */
+export declare function scanProducts(): Product[];
+/**
+ * Get all products (cached). Returns empty array in single-product mode.
+ */
+export declare function getProducts(): Product[];
+/**
+ * Check if the site is in multi-product mode.
+ */
+export declare function isMultiProductMode(): boolean;
+/**
+ * Clear product-related caches. Called by file watchers when _product_.json changes.
+ */
+export declare function clearProductCaches(): void;
 /**
  * Export the loaded config as default (SERVER ONLY)
  */

package/dist/config.server.js

@@ -151,45 +151,68 @@ export function reloadConfig(userConfig) {
  */
 const versionConfigCache = new Map();
 const VCFG_TTL = process.env.NODE_ENV === 'development' ? 5000 : 60000;
-export function loadVersionConfig(version) {
-    const cached = versionConfigCache.get(version);
+export function loadVersionConfig(version, product) {
+    const cacheKey = product && product !== "_default_" ? `${product}:${version}` : version;
+    const cached = versionConfigCache.get(cacheKey);
     if (cached && Date.now() - cached.timestamp < VCFG_TTL) {
         return cached.data;
     }
     try {
-        const versionConfigPath = path.join(process.cwd(), "docs", version, "_version_.json");
+        const basePath = (product && product !== "_default_")
+            ? path.join(process.cwd(), "docs", product, version)
+            : path.join(process.cwd(), "docs", version);
+        const versionConfigPath = path.join(basePath, "_version_.json");
         if (!fs.existsSync(versionConfigPath)) {
-            versionConfigCache.set(version, { data: null, timestamp: Date.now() });
+            versionConfigCache.set(cacheKey, { data: null, timestamp: Date.now() });
             return null;
         }
         const content = fs.readFileSync(versionConfigPath, "utf8");
         const data = JSON.parse(content);
-        versionConfigCache.set(version, { data, timestamp: Date.now() });
+        versionConfigCache.set(cacheKey, { data, timestamp: Date.now() });
         return data;
     }
     catch (error) {
-        console.error(`Error loading _version_.json for ${version}:`, error);
-        versionConfigCache.set(version, { data: null, timestamp: Date.now() });
+        console.error(`Error loading _version_.json for ${cacheKey}:`, error);
+        versionConfigCache.set(cacheKey, { data: null, timestamp: Date.now() });
         return null;
     }
 }
 /**
- * Get the effective config for a specific version.
- * Merges global config with per-version overrides from _version_.json.
- * If no _version_.json exists, returns the global config unchanged.
+ * Get the effective config for a specific version and optional product.
+ * Merges in priority order: global ← product ← version.
+ * If no overrides exist, returns the global config unchanged.
  */
-export function getEffectiveConfig(version) {
+export function getEffectiveConfig(version, product) {
     const globalConfig = getConfig();
-    const versionConfig = loadVersionConfig(version);
-    if (!versionConfig) {
-        return globalConfig;
-    }
-    const effective = { ...globalConfig };
-    if (versionConfig.tabGroups !== undefined) {
-        effective.navigation = {
-            ...effective.navigation,
-            tabGroups: versionConfig.tabGroups,
-        };
+    let effective = { ...globalConfig };
+    // Layer 2: Product config overrides
+    if (product && product !== "_default_") {
+        const productConfig = loadProductConfig(product);
+        if (productConfig) {
+            if (productConfig.tabGroups !== undefined) {
+                effective.navigation = {
+                    ...effective.navigation,
+                    tabGroups: productConfig.tabGroups,
+                };
+            }
+            // Product's activeVersion overrides global
+            if (productConfig.activeVersion) {
+                effective.site = {
+                    ...effective.site,
+                    activeVersion: productConfig.activeVersion,
+                };
+            }
+        }
+    }
+    // Layer 3: Version config overrides (highest priority)
+    const versionConfig = loadVersionConfig(version, product);
+    if (versionConfig) {
+        if (versionConfig.tabGroups !== undefined) {
+            effective.navigation = {
+                ...effective.navigation,
+                tabGroups: versionConfig.tabGroups,
+            };
+        }
     }
     return effective;
 }
@@ -197,9 +220,9 @@ export function getEffectiveConfig(version) {
  * Get metadata for all versions, enriched with _version_.json data.
  * Hidden versions are included but marked — the UI decides whether to show them.
  */
-export function getVersionsMeta(versions) {
+export function getVersionsMeta(versions, product) {
     return versions.map(id => {
-        const versionConfig = loadVersionConfig(id);
+        const versionConfig = loadVersionConfig(id, product);
         return {
             id,
             label: versionConfig?.label || id,
@@ -209,6 +232,145 @@ export function getVersionsMeta(versions) {
         };
     });
 }
+// ─── Product Detection & Loading ─────────────────────────────────────────────
+/** Regex to detect version-like directory names (e.g., v1, v2.0.0) */
+const VERSION_PATTERN = /^v\d/;
+/** Cache for product scanning */
+const productsCache = {
+    data: null,
+    timestamp: 0,
+};
+const PCFG_TTL = process.env.NODE_ENV === 'development' ? 5000 : 60000;
+/** Cache for individual product configs */
+const productConfigCache = new Map();
+/**
+ * Load and parse a _product_.json file for a given product slug.
+ * Returns null if the file doesn't exist or is invalid.
+ */
+export function loadProductConfig(product) {
+    const cached = productConfigCache.get(product);
+    if (cached && Date.now() - cached.timestamp < PCFG_TTL) {
+        return cached.data;
+    }
+    try {
+        const productConfigPath = path.join(process.cwd(), "docs", product, "_product_.json");
+        if (!fs.existsSync(productConfigPath)) {
+            productConfigCache.set(product, { data: null, timestamp: Date.now() });
+            return null;
+        }
+        const content = fs.readFileSync(productConfigPath, "utf8");
+        const data = JSON.parse(content);
+        if (!data.label) {
+            console.error(`[Specra] _product_.json in docs/${product}/ is missing required "label" field`);
+            productConfigCache.set(product, { data: null, timestamp: Date.now() });
+            return null;
+        }
+        productConfigCache.set(product, { data, timestamp: Date.now() });
+        return data;
+    }
+    catch (error) {
+        console.error(`[Specra] Error loading _product_.json for ${product}:`, error);
+        productConfigCache.set(product, { data: null, timestamp: Date.now() });
+        return null;
+    }
+}
+/**
+ * Scan docs/ top-level directories for _product_.json files.
+ * Returns the full list of products including the default product.
+ *
+ * Detection logic:
+ * 1. Single readdir + stat calls — no recursive walks
+ * 2. If no _product_.json found → single-product mode (returns empty array)
+ * 3. If any found → multi-product mode; bare version folders become the default product
+ * 4. Product slugs that match version patterns (e.g., v1.0.0) are rejected with a clear error
+ */
+export function scanProducts() {
+    if (productsCache.data && Date.now() - productsCache.timestamp < PCFG_TTL) {
+        return productsCache.data;
+    }
+    const docsDir = path.join(process.cwd(), "docs");
+    const products = [];
+    let hasExplicitProducts = false;
+    try {
+        const entries = fs.readdirSync(docsDir, { withFileTypes: true });
+        for (const entry of entries) {
+            if (!entry.isDirectory())
+                continue;
+            const productJsonPath = path.join(docsDir, entry.name, "_product_.json");
+            if (!fs.existsSync(productJsonPath))
+                continue;
+            // Validate: product slugs must not look like version names
+            if (VERSION_PATTERN.test(entry.name)) {
+                console.error(`[Specra] Invalid product directory "docs/${entry.name}/": ` +
+                    `product slugs must not start with "v" followed by digits (looks like a version). ` +
+                    `Rename the directory or remove _product_.json.`);
+                continue;
+            }
+            const config = loadProductConfig(entry.name);
+            if (config) {
+                hasExplicitProducts = true;
+                products.push({
+                    slug: entry.name,
+                    config,
+                    isDefault: false,
+                });
+            }
+        }
+    }
+    catch (error) {
+        console.error("[Specra] Error scanning for products:", error);
+    }
+    // Only build a product list if explicit products were found
+    if (!hasExplicitProducts) {
+        productsCache.data = [];
+        productsCache.timestamp = Date.now();
+        return [];
+    }
+    // Add the default product (bare version folders)
+    const globalConfig = getConfig();
+    const defaultProductConfig = globalConfig.site?.defaultProduct;
+    const defaultProduct = {
+        slug: "_default_",
+        config: {
+            label: defaultProductConfig?.label || globalConfig.site?.title || "Docs",
+            icon: defaultProductConfig?.icon,
+            activeVersion: defaultProductConfig?.activeVersion || globalConfig.site?.activeVersion,
+            position: -1, // Default product always first
+        },
+        isDefault: true,
+    };
+    const allProducts = [defaultProduct, ...products];
+    // Sort by position (lower first), then alphabetically by label
+    allProducts.sort((a, b) => {
+        const posA = a.config.position ?? 999;
+        const posB = b.config.position ?? 999;
+        if (posA !== posB)
+            return posA - posB;
+        return a.config.label.localeCompare(b.config.label);
+    });
+    productsCache.data = allProducts;
+    productsCache.timestamp = Date.now();
+    return allProducts;
+}
+/**
+ * Get all products (cached). Returns empty array in single-product mode.
+ */
+export function getProducts() {
+    return scanProducts();
+}
+/**
+ * Check if the site is in multi-product mode.
+ */
+export function isMultiProductMode() {
+    return getProducts().length > 0;
+}
+/**
+ * Clear product-related caches. Called by file watchers when _product_.json changes.
+ */
+export function clearProductCaches() {
+    productsCache.data = null;
+    productConfigCache.clear();
+}
 /**
  * Export the loaded config as default (SERVER ONLY)
  */

package/dist/config.types.d.ts

@@ -34,6 +34,8 @@ export interface SiteConfig {
     hideLogo?: boolean;
     /** Project ID to tie this doc site to a Specra project for visitor tracking */
     projectId?: string;
+    /** Configuration for the default product in multi-product mode */
+    defaultProduct?: DefaultProductConfig;
 }
 /**
  * Theme and appearance settings
@@ -84,6 +86,50 @@ export interface VersionConfig {
     /** Override tab groups for this version. Empty array = no tabs. */
     tabGroups?: TabGroup[];
 }
+/**
+ * Per-product configuration loaded from docs/{product}/_product_.json
+ * Products sit above versions in the config hierarchy.
+ */
+export interface ProductConfig {
+    /** Display name in the product switcher */
+    label: string;
+    /** Icon identifier for the product dropdown (lucide icon name) */
+    icon?: string;
+    /** Short description of the product */
+    description?: string;
+    /** Default version for this product (overrides global site.activeVersion) */
+    activeVersion?: string;
+    /** Badge text shown next to the product (e.g., "New", "Beta") */
+    badge?: string;
+    /** Order in the product dropdown (lower = first) */
+    position?: number;
+    /** Product-level tab group overrides */
+    tabGroups?: TabGroup[];
+}
+/**
+ * Resolved product with its slug and metadata.
+ * Returned by getProducts() — includes both filesystem identity and parsed config.
+ */
+export interface Product {
+    /** Filesystem directory name used in URLs (e.g., "api", "sdk") */
+    slug: string;
+    /** Parsed product configuration from _product_.json */
+    config: ProductConfig;
+    /** Whether this is the default product (bare version folders, no _product_.json) */
+    isDefault: boolean;
+}
+/**
+ * Default product configuration in specra.config.json under site.defaultProduct.
+ * Used when the default product needs a custom label/icon instead of inheriting from site title.
+ */
+export interface DefaultProductConfig {
+    /** Display name for the default product in the switcher */
+    label?: string;
+    /** Icon for the default product */
+    icon?: string;
+    /** Override active version for the default product */
+    activeVersion?: string;
+}
 /**
  * Navigation and sidebar configuration
  */

package/dist/mdx-cache.d.ts

@@ -6,18 +6,15 @@
  * invalidated automatically when files change.
  */
 import type { Doc } from './mdx';
-/**
- * Cached version of getVersions()
- */
-export declare function getCachedVersions(): string[];
+export declare function getCachedVersions(product?: string): string[];
 /**
  * Cached version of getAllDocs()
  */
-export declare function getCachedAllDocs(version?: string, locale?: string): Promise<Doc[]>;
+export declare function getCachedAllDocs(version?: string, locale?: string, product?: string): Promise<Doc[]>;
 /**
  * Cached version of getDocBySlug()
  */
-export declare function getCachedDocBySlug(slug: string, version?: string): Promise<Doc | null>;
+export declare function getCachedDocBySlug(slug: string, version?: string, product?: string): Promise<Doc | null>;
 /**
  * Manually clear all caches
  * Useful for testing or when you want to force a refresh