@vibesdotdev/kit 0.0.0-stage → 1.0.0-rc.3

package/dist/lib/utils/metadata.js

@@ -0,0 +1,221 @@
+/**
+ * Centralized metadata utilities for Vibes application
+ * Provides consistent page titles, SEO metadata, and breadcrumb generation
+ */
+// Default metadata values - fallbacks when system settings are not available
+export const DEFAULT_METADATA = {
+    appName: 'Vibes', // Fallback value
+    separator: ' | ',
+    defaultDescription: 'AI-powered development platform for building and deploying intelligent agents',
+    defaultKeywords: Array.of('AI', 'agents', 'development', 'platform', 'automation', 'knowledge management'),
+    defaultOgImage: '/vibes-logo.png',
+    defaultOgType: 'website',
+    defaultTwitterCard: 'summary',
+    twitterSite: '@vibes_dev',
+    author: 'Vibes Team',
+    robots: 'index, follow'
+};
+let runtimeMetadata = {
+    appName: DEFAULT_METADATA.appName,
+    description: DEFAULT_METADATA.defaultDescription
+};
+/**
+ * Update runtime metadata
+ */
+export function updateMetadata(meta) {
+    runtimeMetadata = { ...runtimeMetadata, ...meta };
+}
+/**
+ * Get current app name (from settings or fallback)
+ */
+export function getAppName() {
+    return runtimeMetadata.appName;
+}
+/**
+ * Get current app description (from settings or fallback)
+ */
+export function getAppDescription() {
+    return runtimeMetadata.description;
+}
+/**
+ * Generate a consistent page title with app name suffix
+ */
+export function generatePageTitle(title, includeAppName = true) {
+    if (!includeAppName) {
+        return title;
+    }
+    return `${title}${DEFAULT_METADATA.separator}${getAppName()}`;
+}
+/**
+ * Generate SEO metadata object with defaults
+ */
+export function generateMetadata(options, location) {
+    const baseUrl = location?.origin ?? '';
+    const currentUrl = location?.href.split('?')[0] ?? '';
+    return {
+        title: generatePageTitle(options.title),
+        description: options.description || getAppDescription(),
+        keywords: options.keywords || DEFAULT_METADATA.defaultKeywords,
+        ogType: options.ogType || DEFAULT_METADATA.defaultOgType,
+        ogImage: options.ogImage || `${baseUrl}${DEFAULT_METADATA.defaultOgImage}`,
+        ogImageAlt: options.ogImageAlt || `${getAppName()} logo`,
+        ogUrl: options.ogUrl || currentUrl,
+        twitterCard: options.twitterCard || DEFAULT_METADATA.defaultTwitterCard,
+        twitterSite: DEFAULT_METADATA.twitterSite,
+        twitterCreator: options.twitterCreator,
+        canonicalUrl: options.canonicalUrl || currentUrl,
+        robots: options.robots || DEFAULT_METADATA.robots,
+        author: options.author || DEFAULT_METADATA.author,
+        publishedTime: options.publishedTime,
+        modifiedTime: options.modifiedTime
+    };
+}
+/**
+ * Generate breadcrumb data structures.
+ * `icon` is an Iconify icon name string (e.g. "lucide:home").
+ */
+export function generateBreadcrumbs(segments) {
+    return segments.map((segment) => ({
+        label: segment.label,
+        href: segment.href,
+        icon: segment.icon
+    }));
+}
+/**
+ * Generate dynamic metadata for chat conversations
+ */
+export function generateChatMetadata(conversationTitle) {
+    const title = conversationTitle ? conversationTitle : 'Conversations';
+    const description = conversationTitle
+        ? `Chat conversation: ${conversationTitle}`
+        : 'AI-powered chat conversations and knowledge assistance';
+    return generateMetadata({
+        title,
+        description,
+        keywords: [...DEFAULT_METADATA.defaultKeywords, 'chat', 'conversations', 'AI assistance'],
+        ogType: 'article'
+    });
+}
+/**
+ * Generate dynamic metadata for knowledge base items
+ */
+export function generateKnowledgeMetadata(itemTitle) {
+    const title = itemTitle ? itemTitle : 'Knowledge Base';
+    const description = itemTitle
+        ? `Knowledge base article: ${itemTitle}`
+        : 'Centralized knowledge management and documentation platform';
+    return generateMetadata({
+        title,
+        description,
+        keywords: [...DEFAULT_METADATA.defaultKeywords, 'knowledge', 'documentation', 'learning'],
+        ogType: 'article'
+    });
+}
+/**
+ * Generate metadata for settings pages
+ */
+export function generateSettingsMetadata(settingsSection) {
+    const title = settingsSection ? `${settingsSection} Settings` : 'Settings';
+    const description = settingsSection
+        ? `Configure ${settingsSection.toLowerCase()} settings and preferences`
+        : 'Application settings and user preferences';
+    return generateMetadata({
+        title,
+        description,
+        keywords: [...DEFAULT_METADATA.defaultKeywords, 'settings', 'preferences', 'configuration'],
+        robots: 'noindex, nofollow' // Settings pages should not be indexed
+    });
+}
+/**
+ * Generate metadata for dashboard
+ */
+export function generateDashboardMetadata() {
+    return generateMetadata({
+        title: 'Dashboard',
+        description: 'AI-powered development platform dashboard - manage projects, agents, and workflows',
+        keywords: [...DEFAULT_METADATA.defaultKeywords, 'dashboard', 'overview', 'projects']
+    });
+}
+/**
+ * Generate JSON-LD structured data for breadcrumbs
+ */
+export function generateBreadcrumbJsonLd(breadcrumbs, location) {
+    const baseUrl = location.origin;
+    const itemListElement = breadcrumbs
+        .filter((breadcrumb) => breadcrumb.href) // Only include items with links
+        .map((breadcrumb, index) => ({
+        '@type': 'ListItem',
+        position: index + 1,
+        name: breadcrumb.label,
+        item: breadcrumb.href?.startsWith('http') ? breadcrumb.href : `${baseUrl}${breadcrumb.href}`
+    }));
+    return JSON.stringify({
+        '@context': 'https://schema.org',
+        '@type': 'BreadcrumbList',
+        itemListElement
+    });
+}
+/**
+ * Common breadcrumb segments for reuse
+ */
+export const BREADCRUMB_SEGMENTS = {
+    dashboard: { label: 'Dashboard', href: '/dashboard' },
+    chat: { label: 'Chat', href: '/chat' },
+    knowledge: { label: 'Knowledge', href: '/knowledge' },
+    settings: { label: 'Settings', href: '/settings' },
+    user: { label: 'Settings', href: '/' },
+    profile: { label: 'Profile', href: '/profile' },
+    apiKeys: { label: 'API Keys', href: '/api-keys' },
+    projects: { label: 'Projects', href: '/projects' }
+};
+/**
+ * Format a date range for display
+ */
+export function formatDateRange(start, end) {
+    const startDate = start instanceof Date ? start : new Date(start);
+    const endDate = end instanceof Date ? end : new Date(end);
+    const options = {
+        month: 'short',
+        day: 'numeric',
+        year: 'numeric'
+    };
+    const startStr = startDate.toLocaleDateString('en-US', options);
+    const endStr = endDate.toLocaleDateString('en-US', options);
+    return `${startStr} - ${endStr}`;
+}
+/**
+ * Format a date as "time ago" (e.g., "2 hours ago", "3 days ago")
+ */
+export function formatTimeAgo(date) {
+    const dateObj = date instanceof Date ? date : new Date(date);
+    const now = new Date();
+    const seconds = Math.floor((now.getTime() - dateObj.getTime()) / 1000);
+    if (seconds < 60)
+        return 'just now';
+    const minutes = Math.floor(seconds / 60);
+    if (minutes < 60)
+        return `${minutes} minute${minutes > 1 ? 's' : ''} ago`;
+    const hours = Math.floor(minutes / 60);
+    if (hours < 24)
+        return `${hours} hour${hours > 1 ? 's' : ''} ago`;
+    const days = Math.floor(hours / 24);
+    if (days < 30)
+        return `${days} day${days > 1 ? 's' : ''} ago`;
+    const months = Math.floor(days / 30);
+    if (months < 12)
+        return `${months} month${months > 1 ? 's' : ''} ago`;
+    const years = Math.floor(months / 12);
+    return `${years} year${years > 1 ? 's' : ''} ago`;
+}
+function isCompositeMetadata(value) {
+    return typeof value === 'object' && value !== null;
+}
+/**
+ * Format metadata object into display strings
+ */
+export function formatMetadata(metadata) {
+    return Object.entries(metadata).map(([key, value]) => ({
+        key,
+        value: isCompositeMetadata(value) ? JSON.stringify(value) : String(value)
+    }));
+}

package/dist/lib/utils/page-meta.d.ts

@@ -0,0 +1,115 @@
+/**
+ * One place that knows what a correct social/SEO head looks like.
+ *
+ * WHY THIS GREW: every app hand-rolled its own `<meta>` block in
+ * `+layout.svelte`, and each one was incomplete in a different way. The shared
+ * failures, measured across apps before this existed:
+ *
+ *   - `og:image` pointed at a 590x590 logo while `twitter:card` claimed
+ *     `summary_large_image` (which is 1200x630, 1.91:1) — so every share on X,
+ *     LinkedIn, Slack, Discord and iMessage cropped or letterboxed a bare logo.
+ *   - no `og:url`, so platforms could not resolve a canonical target
+ *   - no `og:image:width`/`height`, which is what lets a crawler lay out the
+ *     card on FIRST fetch instead of rendering a blank box until it downloads
+ *     the image
+ *   - no `twitter:image`, so X fell back to guessing
+ *   - no `og:site_name`, no canonical link
+ *
+ * The tag set is returned as DATA, not markup, so the same source can drive a
+ * Svelte `<svelte:head>` (see `components/seo/SeoMeta.svelte`), a server-rendered
+ * string, or a test that asserts the tags without mounting a component.
+ */
+/** The shared 1200x630 share card. Generated by `bun run og:card`. */
+export declare const DEFAULT_OG_CARD_PATH = "/og/default.jpg";
+/** Intrinsic size of every card `bun run og:card` emits. */
+export declare const OG_CARD_WIDTH = 1200;
+export declare const OG_CARD_HEIGHT = 630;
+export interface PageMeta {
+    title: string;
+    description?: string;
+    keywords?: string[];
+    ogType?: string;
+    ogImage?: string;
+    twitterCard?: string;
+    robots?: string;
+}
+export declare const defaultPageMeta: PageMeta;
+export declare function buildPageTitle(title: string, template?: string): string;
+export interface SeoInput {
+    /** Page title, used verbatim for `<title>`, `og:title`, `twitter:title`. */
+    title: string;
+    description?: string;
+    /** Absolute URL of THIS page. Drives `og:url` and `<link rel=canonical>`. */
+    url?: string;
+    /** Origin that serves the static assets, e.g. `https://assets.vibes.dev`. */
+    assetsOrigin?: string;
+    /** Path or absolute URL of the share card. Defaults to the shared card. */
+    image?: string;
+    imageAlt?: string;
+    /** Site/product name for `og:site_name`. */
+    siteName?: string;
+    ogType?: string;
+    keywords?: string[];
+    robots?: string;
+    /** e.g. `@vibes_dev` */
+    twitterSite?: string;
+    /** Browser icon path or absolute URL. Defaults to the shared Vibes favicon. */
+    favicon?: string;
+    /** Optional dark-mode browser icon. */
+    faviconDark?: string;
+    /** Optional iOS home-screen icon. Defaults to the favicon. */
+    appleTouchIcon?: string;
+    /** Optional web-app manifest path or absolute URL. */
+    manifest?: string;
+    /** Optional browser UI colour, normally supplied by the branding manifest. */
+    themeColor?: string;
+}
+/** Runtime manifest shape deliberately kept structural so Kit never imports an app domain package. */
+export interface BrandingMetaInput {
+    name: string;
+    description?: string;
+    favicon?: string;
+    ogImage?: string;
+    url?: string;
+    colors?: {
+        primary?: string;
+    };
+}
+export interface SeoTag {
+    name?: string;
+    property?: string;
+    content: string;
+}
+export interface SeoTags {
+    title: string;
+    canonical?: string;
+    icon: string;
+    iconDark?: string;
+    appleTouchIcon: string;
+    manifest?: string;
+    themeColor?: string;
+    tags: SeoTag[];
+}
+/**
+ * Make an image reference absolute.
+ *
+ * Every major crawler rejects a relative `og:image`; this is the single most
+ * common reason a card renders blank. If a caller passes an absolute URL we
+ * keep it, otherwise we join it onto the assets origin.
+ */
+export declare function resolveOgImage(image: string, assetsOrigin?: string): string;
+/** Resolve any static asset against the CDN, falling back to the request origin for local SvelteKit. */
+export declare function resolveSeoAsset(asset: string, assetsOrigin?: string, pageUrl?: string): string;
+/**
+ * Adapt a runtime-resolved app.branding manifest to the framework-neutral Kit input.
+ * The SvelteKit layout still owns runtime bootstrapping and request URL selection.
+ */
+export declare function seoInputFromBranding(branding: BrandingMetaInput, overrides?: Partial<SeoInput>): SeoInput;
+/**
+ * Build the complete tag set for a page.
+ *
+ * Deliberately emits `og:image:width`/`height` whenever the image is one of our
+ * own cards: those dimensions are what let a crawler reserve the right box on
+ * first fetch rather than showing an empty frame until the bytes arrive.
+ */
+export declare function buildSeoMeta(input: SeoInput): SeoTags;

package/dist/lib/utils/page-meta.js

@@ -0,0 +1,132 @@
+/**
+ * One place that knows what a correct social/SEO head looks like.
+ *
+ * WHY THIS GREW: every app hand-rolled its own `<meta>` block in
+ * `+layout.svelte`, and each one was incomplete in a different way. The shared
+ * failures, measured across apps before this existed:
+ *
+ *   - `og:image` pointed at a 590x590 logo while `twitter:card` claimed
+ *     `summary_large_image` (which is 1200x630, 1.91:1) — so every share on X,
+ *     LinkedIn, Slack, Discord and iMessage cropped or letterboxed a bare logo.
+ *   - no `og:url`, so platforms could not resolve a canonical target
+ *   - no `og:image:width`/`height`, which is what lets a crawler lay out the
+ *     card on FIRST fetch instead of rendering a blank box until it downloads
+ *     the image
+ *   - no `twitter:image`, so X fell back to guessing
+ *   - no `og:site_name`, no canonical link
+ *
+ * The tag set is returned as DATA, not markup, so the same source can drive a
+ * Svelte `<svelte:head>` (see `components/seo/SeoMeta.svelte`), a server-rendered
+ * string, or a test that asserts the tags without mounting a component.
+ */
+/** The shared 1200x630 share card. Generated by `bun run og:card`. */
+export const DEFAULT_OG_CARD_PATH = '/og/default.jpg';
+/** Intrinsic size of every card `bun run og:card` emits. */
+export const OG_CARD_WIDTH = 1200;
+export const OG_CARD_HEIGHT = 630;
+export const defaultPageMeta = {
+    title: 'Vibes',
+    description: 'A comprehensive AI platform for knowledge management, agent orchestration, and intelligent workflows',
+    keywords: ['Vibes', 'AI', 'platform', 'knowledge management'],
+    ogType: 'website',
+    ogImage: DEFAULT_OG_CARD_PATH,
+    // A 1200x630 card IS a large card. The old default said `summary`, which asks
+    // platforms to render a small square crop of a wide image.
+    twitterCard: 'summary_large_image',
+    robots: 'index, follow'
+};
+export function buildPageTitle(title, template = '%s - Vibes') {
+    return template.replace('%s', title);
+}
+/**
+ * Make an image reference absolute.
+ *
+ * Every major crawler rejects a relative `og:image`; this is the single most
+ * common reason a card renders blank. If a caller passes an absolute URL we
+ * keep it, otherwise we join it onto the assets origin.
+ */
+export function resolveOgImage(image, assetsOrigin) {
+    if (/^https?:\/\//i.test(image))
+        return image;
+    if (!assetsOrigin)
+        return image;
+    return `${assetsOrigin.replace(/\/$/, '')}/${image.replace(/^\//, '')}`;
+}
+/** Resolve any static asset against the CDN, falling back to the request origin for local SvelteKit. */
+export function resolveSeoAsset(asset, assetsOrigin, pageUrl) {
+    if (/^https?:\/\//i.test(asset))
+        return asset;
+    const origin = assetsOrigin || (pageUrl ? new URL(pageUrl).origin : undefined);
+    return resolveOgImage(asset, origin);
+}
+/**
+ * Adapt a runtime-resolved app.branding manifest to the framework-neutral Kit input.
+ * The SvelteKit layout still owns runtime bootstrapping and request URL selection.
+ */
+export function seoInputFromBranding(branding, overrides = {}) {
+    return {
+        title: branding.name,
+        description: branding.description,
+        image: branding.ogImage,
+        url: branding.url,
+        themeColor: branding.colors?.primary,
+        favicon: branding.favicon,
+        ...overrides
+    };
+}
+/**
+ * Build the complete tag set for a page.
+ *
+ * Deliberately emits `og:image:width`/`height` whenever the image is one of our
+ * own cards: those dimensions are what let a crawler reserve the right box on
+ * first fetch rather than showing an empty frame until the bytes arrive.
+ */
+export function buildSeoMeta(input) {
+    const { title, description, url, assetsOrigin, image = DEFAULT_OG_CARD_PATH, imageAlt, siteName = 'Vibes', ogType = 'website', keywords, robots = 'index, follow', twitterSite, favicon = '/favicon.svg', faviconDark, appleTouchIcon = favicon, manifest, themeColor } = input;
+    const imageUrl = resolveSeoAsset(image, assetsOrigin, url);
+    const icon = resolveSeoAsset(favicon, assetsOrigin, url);
+    const iconDark = faviconDark ? resolveSeoAsset(faviconDark, assetsOrigin, url) : undefined;
+    const appleIcon = resolveSeoAsset(appleTouchIcon, assetsOrigin, url);
+    const manifestUrl = manifest ? resolveSeoAsset(manifest, assetsOrigin, url) : undefined;
+    const isOwnCard = imageUrl.includes('/og/');
+    const tags = [];
+    if (description)
+        tags.push({ name: 'description', content: description });
+    if (keywords?.length)
+        tags.push({ name: 'keywords', content: keywords.join(', ') });
+    tags.push({ name: 'robots', content: robots });
+    tags.push({ property: 'og:title', content: title });
+    if (description)
+        tags.push({ property: 'og:description', content: description });
+    tags.push({ property: 'og:type', content: ogType });
+    tags.push({ property: 'og:site_name', content: siteName });
+    if (url)
+        tags.push({ property: 'og:url', content: url });
+    tags.push({ property: 'og:image', content: imageUrl });
+    if (isOwnCard) {
+        tags.push({ property: 'og:image:width', content: String(OG_CARD_WIDTH) });
+        tags.push({ property: 'og:image:height', content: String(OG_CARD_HEIGHT) });
+        tags.push({ property: 'og:image:type', content: 'image/jpeg' });
+    }
+    tags.push({ property: 'og:image:alt', content: imageAlt ?? `${title} — ${siteName}` });
+    // Twitter reads og:* for most fields but needs its own card + image to pick
+    // the wide layout reliably across clients.
+    tags.push({ name: 'twitter:card', content: 'summary_large_image' });
+    tags.push({ name: 'twitter:title', content: title });
+    if (description)
+        tags.push({ name: 'twitter:description', content: description });
+    tags.push({ name: 'twitter:image', content: imageUrl });
+    tags.push({ name: 'twitter:image:alt', content: imageAlt ?? `${title} — ${siteName}` });
+    if (twitterSite)
+        tags.push({ name: 'twitter:site', content: twitterSite });
+    return {
+        title,
+        canonical: url,
+        icon,
+        iconDark,
+        appleTouchIcon: appleIcon,
+        manifest: manifestUrl,
+        themeColor,
+        tags
+    };
+}

package/dist/lib/utils.d.ts

@@ -0,0 +1,17 @@
+import { type ClassValue } from 'clsx';
+export declare function cn(...inputs: ClassValue[]): string;
+export type WithoutChild<T> = T extends {
+    child?: unknown;
+} ? Omit<T, 'child'> : T;
+export type WithoutChildren<T> = T extends {
+    children?: unknown;
+} ? Omit<T, 'children'> : T;
+export type WithoutChildrenOrChild<T> = WithoutChildren<WithoutChild<T>>;
+export type WithElementRef<T, U extends HTMLElement = HTMLElement> = T & {
+    ref?: U | null;
+};
+/**
+ * Debounce: delay invoking `func` until `wait` ms have elapsed since the last
+ * call; each call resets the timer. UI-local timer primitive (D6 LEGIT).
+ */
+export declare function debounce<T extends (...args: never[]) => void>(func: T, wait: number): (...args: Parameters<T>) => void;

package/dist/lib/utils.js

@@ -0,0 +1,36 @@
+import { clsx } from 'clsx';
+import { extendTailwindMerge } from 'tailwind-merge';
+/**
+ * Tailwind Merge cannot discover CSS-first `@theme` tokens by itself. Without
+ * this extension it mistakes `text-caption`/`text-footnote` for text colors,
+ * so composing either with `text-muted-foreground` silently deletes the type
+ * token. Keep Kit's named typography scale in the `text` theme group so size
+ * and color remain independent while later size tokens still replace earlier
+ * ones.
+ */
+const mergeClasses = extendTailwindMerge({
+    extend: {
+        theme: {
+            text: ['large-title', 'title', 'headline', 'callout', 'footnote', 'caption']
+        }
+    }
+});
+export function cn(...inputs) {
+    return mergeClasses(clsx(inputs));
+}
+/**
+ * Debounce: delay invoking `func` until `wait` ms have elapsed since the last
+ * call; each call resets the timer. UI-local timer primitive (D6 LEGIT).
+ */
+export function debounce(func, wait) {
+    let timeout = null;
+    return function (...args) {
+        if (timeout) {
+            clearTimeout(timeout);
+        }
+        // LEGIT (D6): UI-local debounce, browser/UI timer.
+        timeout = setTimeout(() => {
+            func(...args);
+        }, wait);
+    };
+}