@quilltap/plugin-types 1.0.2 → 1.1.0

package/dist/index-BJhI-WMr.d.mts

@@ -0,0 +1,834 @@
+import { ReactNode } from 'react';
+import { LLMProvider, ImageGenProvider, ToolFormatOptions, ToolCallRequest } from './llm/index.mjs';
+
+/**
+ * Provider Plugin Interface types for Quilltap plugin development
+ *
+ * @module @quilltap/plugin-types/plugins/provider
+ */
+
+/**
+ * Provider metadata for UI display and identification
+ */
+interface ProviderMetadata {
+    /** Internal identifier for the provider (e.g., 'OPENAI', 'ANTHROPIC') */
+    providerName: string;
+    /** Human-readable display name for UI (e.g., 'OpenAI', 'Anthropic') */
+    displayName: string;
+    /** Short description of the provider */
+    description: string;
+    /** Short abbreviation for icon display (e.g., 'OAI', 'ANT') */
+    abbreviation: string;
+    /** Tailwind CSS color classes for UI styling */
+    colors: {
+        /** Background color class (e.g., 'bg-green-100') */
+        bg: string;
+        /** Text color class (e.g., 'text-green-800') */
+        text: string;
+        /** Icon color class (e.g., 'text-green-600') */
+        icon: string;
+    };
+}
+/**
+ * Configuration requirements for the provider
+ */
+interface ProviderConfigRequirements {
+    /** Whether this provider requires an API key */
+    requiresApiKey: boolean;
+    /** Whether this provider requires a custom base URL */
+    requiresBaseUrl: boolean;
+    /** Label text for API key input field */
+    apiKeyLabel?: string;
+    /** Label text for base URL input field */
+    baseUrlLabel?: string;
+    /** Placeholder text for base URL input */
+    baseUrlPlaceholder?: string;
+    /** Default value for base URL */
+    baseUrlDefault?: string;
+    /** Deprecated: use baseUrlDefault instead */
+    defaultBaseUrl?: string;
+}
+/**
+ * Provider capability flags
+ */
+interface ProviderCapabilities {
+    /** Whether the provider supports chat completions */
+    chat: boolean;
+    /** Whether the provider supports image generation */
+    imageGeneration: boolean;
+    /** Whether the provider supports text embeddings */
+    embeddings: boolean;
+    /** Whether the provider supports web search functionality */
+    webSearch: boolean;
+}
+/**
+ * Attachment/file support configuration
+ */
+interface AttachmentSupport {
+    /** Whether this provider supports file attachments */
+    supportsAttachments: boolean;
+    /** Array of MIME types supported for attachments */
+    supportedMimeTypes: string[];
+    /** Human-readable description of attachment support */
+    description: string;
+    /** Additional notes about attachment support or limitations */
+    notes?: string;
+    /** Maximum file size in bytes */
+    maxFileSize?: number;
+    /** Maximum number of files per request */
+    maxFiles?: number;
+}
+/**
+ * Information about a specific model
+ */
+interface ModelInfo {
+    /** Unique identifier for the model */
+    id: string;
+    /** Human-readable name of the model */
+    name: string;
+    /** Context window size (tokens) */
+    contextWindow?: number;
+    /** Maximum output tokens for this model */
+    maxOutputTokens?: number;
+    /** Whether this model supports image attachments */
+    supportsImages?: boolean;
+    /** Whether this model supports tool/function calling */
+    supportsTools?: boolean;
+    /** Description of the model */
+    description?: string;
+    /** Pricing information */
+    pricing?: {
+        /** Price per 1M input tokens */
+        input: number;
+        /** Price per 1M output tokens */
+        output: number;
+    };
+}
+/**
+ * Information about an embedding model
+ */
+interface EmbeddingModelInfo {
+    /** Unique identifier for the embedding model */
+    id: string;
+    /** Human-readable name of the model */
+    name: string;
+    /** Dimensions of the embedding vector output */
+    dimensions?: number;
+    /** Description of the model's characteristics */
+    description?: string;
+}
+/**
+ * Information about an image generation model
+ */
+interface ImageGenerationModelInfo {
+    /** Unique identifier for the model */
+    id: string;
+    /** Human-readable name of the model */
+    name: string;
+    /** Supported aspect ratios (e.g., ['1:1', '16:9']) */
+    supportedAspectRatios?: string[];
+    /** Supported image sizes (e.g., ['1024x1024', '512x512']) */
+    supportedSizes?: string[];
+    /** Description of the model */
+    description?: string;
+}
+/**
+ * Constraints for image generation
+ */
+interface ImageProviderConstraints {
+    /** Maximum bytes allowed for image generation prompt */
+    maxPromptBytes?: number;
+    /** Warning message about prompt constraints */
+    promptConstraintWarning?: string;
+    /** Maximum images per request */
+    maxImagesPerRequest?: number;
+    /** Supported aspect ratios */
+    supportedAspectRatios?: string[];
+    /** Supported image sizes */
+    supportedSizes?: string[];
+}
+/**
+ * Icon component props
+ */
+interface IconProps {
+    /** CSS class for styling */
+    className?: string;
+}
+/**
+ * Message format support for multi-character chats
+ * Defines how the provider handles the 'name' field in messages
+ */
+interface MessageFormatSupport {
+    /** Whether the provider supports a name field on messages */
+    supportsNameField: boolean;
+    /** Which roles support the name field */
+    supportedRoles: ('user' | 'assistant')[];
+    /** Maximum length for name field (if limited) */
+    maxNameLength?: number;
+}
+/**
+ * Cheap model configuration for background tasks
+ * Used for memory extraction, summarization, titling, etc.
+ */
+interface CheapModelConfig {
+    /** The default cheap model for this provider */
+    defaultModel: string;
+    /** List of recommended cheap models */
+    recommendedModels: string[];
+}
+/**
+ * Tool format type for this provider
+ * Determines how tools are formatted for API calls
+ */
+type ToolFormatType = 'openai' | 'anthropic' | 'google';
+/**
+ * Main LLM Provider Plugin Interface
+ *
+ * Plugins implementing this interface can be dynamically loaded
+ * by Quilltap to provide LLM functionality from various providers.
+ *
+ * @example
+ * ```typescript
+ * import type { LLMProviderPlugin } from '@quilltap/plugin-types';
+ *
+ * export const plugin: LLMProviderPlugin = {
+ *   metadata: {
+ *     providerName: 'MY_PROVIDER',
+ *     displayName: 'My Provider',
+ *     description: 'Custom LLM provider',
+ *     abbreviation: 'MYP',
+ *     colors: { bg: 'bg-blue-100', text: 'text-blue-800', icon: 'text-blue-600' },
+ *   },
+ *   config: {
+ *     requiresApiKey: true,
+ *     requiresBaseUrl: false,
+ *     apiKeyLabel: 'API Key',
+ *   },
+ *   capabilities: {
+ *     chat: true,
+ *     imageGeneration: false,
+ *     embeddings: false,
+ *     webSearch: false,
+ *   },
+ *   attachmentSupport: {
+ *     supportsAttachments: false,
+ *     supportedMimeTypes: [],
+ *     description: 'No file attachments supported',
+ *   },
+ *   createProvider: () => new MyProvider(),
+ *   getAvailableModels: async (apiKey) => [...],
+ *   validateApiKey: async (apiKey) => {...},
+ *   renderIcon: ({ className }) => <MyIcon className={className} />,
+ * };
+ * ```
+ */
+interface LLMProviderPlugin {
+    /** Provider metadata for UI display and identification */
+    metadata: ProviderMetadata;
+    /** Configuration requirements for this provider */
+    config: ProviderConfigRequirements;
+    /** Supported capabilities for this provider */
+    capabilities: ProviderCapabilities;
+    /** File attachment support information */
+    attachmentSupport: AttachmentSupport;
+    /**
+     * Factory method to create an LLMProvider instance
+     * @param baseUrl Optional base URL for the provider
+     */
+    createProvider: (baseUrl?: string) => LLMProvider;
+    /**
+     * Factory method to create an ImageGenProvider instance (optional)
+     * Only required if capabilities.imageGeneration is true
+     * @param baseUrl Optional base URL for the provider
+     */
+    createImageProvider?: (baseUrl?: string) => ImageGenProvider;
+    /**
+     * Factory method to create an embedding provider (optional)
+     * Only required if capabilities.embeddings is true
+     * @param baseUrl Optional base URL for the provider
+     */
+    createEmbeddingProvider?: (baseUrl?: string) => unknown;
+    /**
+     * Get list of available models for this provider
+     * @param apiKey API key for authentication
+     * @param baseUrl Optional base URL
+     */
+    getAvailableModels: (apiKey: string, baseUrl?: string) => Promise<string[]>;
+    /**
+     * Get static model information without API calls
+     */
+    getModelInfo?: () => ModelInfo[];
+    /**
+     * Get embedding models supported by this provider
+     */
+    getEmbeddingModels?: () => EmbeddingModelInfo[];
+    /**
+     * Get image generation models supported by this provider
+     */
+    getImageGenerationModels?: () => ImageGenerationModelInfo[];
+    /**
+     * Validate an API key for this provider
+     * @param apiKey API key to validate
+     * @param baseUrl Optional base URL
+     */
+    validateApiKey: (apiKey: string, baseUrl?: string) => Promise<boolean>;
+    /**
+     * Render the provider icon as a React component
+     * @param props Icon component props
+     */
+    renderIcon: (props: IconProps) => ReactNode;
+    /**
+     * Convert universal tool format to provider-specific format (optional)
+     * @param tool Tools in OpenAI format or generic objects
+     * @param options Formatting options
+     */
+    formatTools?: (tool: any, options?: ToolFormatOptions) => any;
+    /**
+     * Parse provider-specific tool calls from response (optional)
+     * @param response Raw API response
+     */
+    parseToolCalls?: (response: any) => ToolCallRequest[];
+    /**
+     * Get image provider constraints (optional)
+     * Only applicable for providers with imageGeneration capability
+     */
+    getImageProviderConstraints?: () => ImageProviderConstraints;
+    /**
+     * Message format support for multi-character contexts (optional)
+     * If not provided, defaults to no name field support
+     */
+    messageFormat?: MessageFormatSupport;
+    /**
+     * Token estimation multiplier (optional)
+     * Characters per token for this provider's tokenizer
+     * @default 3.5
+     */
+    charsPerToken?: number;
+    /**
+     * Tool format type for this provider (optional)
+     * Used for quick format detection without calling formatTools()
+     * @default 'openai'
+     */
+    toolFormat?: ToolFormatType;
+    /**
+     * Cheap model configuration for background tasks (optional)
+     * Used for memory extraction, summarization, titling, etc.
+     */
+    cheapModels?: CheapModelConfig;
+    /**
+     * Default context window when model is unknown (optional)
+     * Falls back to 8192 if not specified
+     */
+    defaultContextWindow?: number;
+}
+/**
+ * Standard export type for provider plugins
+ */
+interface ProviderPluginExport {
+    /** The provider plugin instance */
+    plugin: LLMProviderPlugin;
+}
+
+/**
+ * Plugin Manifest types for Quilltap plugin development
+ *
+ * @module @quilltap/plugin-types/plugins/manifest
+ */
+/**
+ * Plugin capability types
+ */
+type PluginCapability = 'LLM_PROVIDER' | 'AUTH_PROVIDER' | 'STORAGE_BACKEND' | 'THEME' | 'UTILITY';
+/**
+ * Plugin category
+ */
+type PluginCategory = 'PROVIDER' | 'AUTH' | 'STORAGE' | 'UI' | 'UTILITY';
+/**
+ * Plugin status
+ */
+type PluginStatus = 'STABLE' | 'BETA' | 'EXPERIMENTAL' | 'DEPRECATED';
+/**
+ * Author information
+ */
+interface PluginAuthor {
+    /** Author name */
+    name: string;
+    /** Author email */
+    email?: string;
+    /** Author website or profile URL */
+    url?: string;
+}
+/**
+ * Compatibility requirements
+ */
+interface PluginCompatibility {
+    /** Minimum Quilltap version (semver range) */
+    quilltapVersion: string;
+    /** Minimum Node.js version (semver range) */
+    nodeVersion?: string;
+}
+/**
+ * Provider-specific configuration (for LLM_PROVIDER plugins)
+ */
+interface ProviderConfig {
+    /** Internal provider name */
+    providerName: string;
+    /** Human-readable display name */
+    displayName: string;
+    /** Provider description */
+    description: string;
+    /** Short abbreviation */
+    abbreviation: string;
+    /** UI color configuration */
+    colors: {
+        bg: string;
+        text: string;
+        icon: string;
+    };
+    /** Whether the provider requires an API key */
+    requiresApiKey: boolean;
+    /** Whether the provider requires a base URL */
+    requiresBaseUrl: boolean;
+    /** Label for API key input */
+    apiKeyLabel?: string;
+    /** Provider capabilities */
+    capabilities: {
+        chat: boolean;
+        imageGeneration: boolean;
+        embeddings: boolean;
+        webSearch: boolean;
+    };
+    /** Attachment support configuration */
+    attachmentSupport: {
+        supported: boolean;
+        mimeTypes: string[];
+        description: string;
+    };
+}
+/**
+ * Required permissions for the plugin
+ */
+interface PluginPermissions {
+    /** Network domains the plugin may access */
+    network?: string[];
+    /** Whether the plugin accesses user data */
+    userData?: boolean;
+    /** Whether the plugin accesses the database */
+    database?: boolean;
+    /** Whether the plugin accesses the file system */
+    fileSystem?: boolean;
+}
+/**
+ * Plugin manifest schema
+ *
+ * This is the structure of the quilltap-manifest.json file
+ * that every Quilltap plugin must include.
+ */
+interface PluginManifest {
+    /** JSON schema reference */
+    $schema?: string;
+    /** Package name (must start with qtap-plugin-) */
+    name: string;
+    /** Human-readable title */
+    title: string;
+    /** Plugin description */
+    description: string;
+    /** Semantic version */
+    version: string;
+    /** Author information */
+    author: PluginAuthor;
+    /** License identifier (SPDX) */
+    license: string;
+    /** Compatibility requirements */
+    compatibility: PluginCompatibility;
+    /** Plugin capabilities */
+    capabilities: PluginCapability[];
+    /** Plugin category */
+    category: PluginCategory;
+    /** Main entry point (relative path) */
+    main: string;
+    /** Whether TypeScript source is available */
+    typescript?: boolean;
+    /** Frontend framework used */
+    frontend?: 'REACT' | 'NONE';
+    /** Styling approach used */
+    styling?: 'TAILWIND' | 'CSS' | 'NONE';
+    /** Whether to enable by default when installed */
+    enabledByDefault?: boolean;
+    /** Plugin status */
+    status: PluginStatus;
+    /** Search keywords */
+    keywords?: string[];
+    /** Provider-specific configuration (for LLM_PROVIDER plugins) */
+    providerConfig?: ProviderConfig;
+    /** Required permissions */
+    permissions?: PluginPermissions;
+    /** Repository URL */
+    repository?: string | {
+        type: string;
+        url: string;
+        directory?: string;
+    };
+    /** Homepage URL */
+    homepage?: string;
+    /** Bug tracker URL */
+    bugs?: string | {
+        url: string;
+        email?: string;
+    };
+}
+/**
+ * Installed plugin metadata
+ * Extended manifest with installation-specific information
+ */
+interface InstalledPluginInfo extends PluginManifest {
+    /** Whether the plugin is currently enabled */
+    enabled: boolean;
+    /** Installation timestamp */
+    installedAt?: string;
+    /** Last update timestamp */
+    updatedAt?: string;
+    /** Installation scope */
+    scope?: 'site' | 'user';
+    /** Path to installed plugin */
+    installPath?: string;
+}
+
+/**
+ * Theme Plugin Interface types for Quilltap plugin development
+ *
+ * @module @quilltap/plugin-types/plugins/theme
+ */
+/**
+ * Color palette for a single color mode (light or dark)
+ *
+ * Colors can be specified as:
+ * - HSL values: "222.2 84% 4.9%" (without hsl() wrapper)
+ * - Full HSL: "hsl(222.2 84% 4.9%)"
+ * - Hex: "#1a1a2e"
+ * - Other valid CSS color values: rgb(), oklch(), etc.
+ */
+interface ColorPalette {
+    /** Main background color */
+    background: string;
+    /** Main text color */
+    foreground: string;
+    /** Primary brand/action color */
+    primary: string;
+    /** Text on primary color */
+    primaryForeground: string;
+    /** Secondary background color */
+    secondary: string;
+    /** Text on secondary color */
+    secondaryForeground: string;
+    /** Muted background for less prominent elements */
+    muted: string;
+    /** Muted text color */
+    mutedForeground: string;
+    /** Accent color for highlights */
+    accent: string;
+    /** Text on accent color */
+    accentForeground: string;
+    /** Error/destructive action color */
+    destructive: string;
+    /** Text on destructive color */
+    destructiveForeground: string;
+    /** Card background color */
+    card: string;
+    /** Card text color */
+    cardForeground: string;
+    /** Popover/dropdown background */
+    popover: string;
+    /** Popover text color */
+    popoverForeground: string;
+    /** Default border color */
+    border: string;
+    /** Input field border color */
+    input: string;
+    /** Focus ring color */
+    ring: string;
+    /** Success state color */
+    success?: string;
+    /** Text on success color */
+    successForeground?: string;
+    /** Warning state color */
+    warning?: string;
+    /** Text on warning color */
+    warningForeground?: string;
+    /** Info state color */
+    info?: string;
+    /** Text on info color */
+    infoForeground?: string;
+    /** User message bubble background */
+    chatUser?: string;
+    /** User message bubble text */
+    chatUserForeground?: string;
+}
+/**
+ * Typography token configuration
+ */
+interface Typography {
+    /** Sans-serif font stack (default: "Inter, system-ui, sans-serif") */
+    fontSans?: string;
+    /** Serif font stack (default: "Georgia, serif") */
+    fontSerif?: string;
+    /** Monospace font stack (default: "ui-monospace, SFMono-Regular, monospace") */
+    fontMono?: string;
+    /** Extra small text - 12px (default: "0.75rem") */
+    fontSizeXs?: string;
+    /** Small text - 14px (default: "0.875rem") */
+    fontSizeSm?: string;
+    /** Base text size - 16px (default: "1rem") */
+    fontSizeBase?: string;
+    /** Large text - 18px (default: "1.125rem") */
+    fontSizeLg?: string;
+    /** Extra large text - 20px (default: "1.25rem") */
+    fontSizeXl?: string;
+    /** 2XL text - 24px (default: "1.5rem") */
+    fontSize2xl?: string;
+    /** 3XL text - 30px (default: "1.875rem") */
+    fontSize3xl?: string;
+    /** 4XL text - 36px (default: "2.25rem") */
+    fontSize4xl?: string;
+    /** Tight line height (default: "1.25") */
+    lineHeightTight?: string;
+    /** Normal line height (default: "1.5") */
+    lineHeightNormal?: string;
+    /** Relaxed line height (default: "1.75") */
+    lineHeightRelaxed?: string;
+    /** Normal font weight (default: "400") */
+    fontWeightNormal?: string;
+    /** Medium font weight (default: "500") */
+    fontWeightMedium?: string;
+    /** Semibold font weight (default: "600") */
+    fontWeightSemibold?: string;
+    /** Bold font weight (default: "700") */
+    fontWeightBold?: string;
+    /** Tight letter spacing (default: "-0.025em") */
+    letterSpacingTight?: string;
+    /** Normal letter spacing (default: "0") */
+    letterSpacingNormal?: string;
+    /** Wide letter spacing (default: "0.025em") */
+    letterSpacingWide?: string;
+}
+/**
+ * Spacing and layout token configuration
+ */
+interface Spacing {
+    /** Small border radius (default: "calc(0.5rem - 4px)") */
+    radiusSm?: string;
+    /** Medium border radius (default: "calc(0.5rem - 2px)") */
+    radiusMd?: string;
+    /** Large border radius (default: "0.5rem") */
+    radiusLg?: string;
+    /** Extra large border radius (default: "0.75rem") */
+    radiusXl?: string;
+    /** Full/pill border radius (default: "9999px") */
+    radiusFull?: string;
+    /** 4px spacing (default: "0.25rem") */
+    spacing1?: string;
+    /** 8px spacing (default: "0.5rem") */
+    spacing2?: string;
+    /** 12px spacing (default: "0.75rem") */
+    spacing3?: string;
+    /** 16px spacing (default: "1rem") */
+    spacing4?: string;
+    /** 20px spacing (default: "1.25rem") */
+    spacing5?: string;
+    /** 24px spacing (default: "1.5rem") */
+    spacing6?: string;
+    /** 32px spacing (default: "2rem") */
+    spacing8?: string;
+    /** 40px spacing (default: "2.5rem") */
+    spacing10?: string;
+    /** 48px spacing (default: "3rem") */
+    spacing12?: string;
+    /** 64px spacing (default: "4rem") */
+    spacing16?: string;
+}
+/**
+ * Visual effects token configuration
+ */
+interface Effects {
+    /** Small shadow (default: "0 1px 2px 0 rgb(0 0 0 / 0.05)") */
+    shadowSm?: string;
+    /** Medium shadow (default: "0 4px 6px -1px rgb(0 0 0 / 0.1)") */
+    shadowMd?: string;
+    /** Large shadow (default: "0 10px 15px -3px rgb(0 0 0 / 0.1)") */
+    shadowLg?: string;
+    /** Extra large shadow (default: "0 20px 25px -5px rgb(0 0 0 / 0.1)") */
+    shadowXl?: string;
+    /** Fast transition duration (default: "150ms") */
+    transitionFast?: string;
+    /** Normal transition duration (default: "200ms") */
+    transitionNormal?: string;
+    /** Slow transition duration (default: "300ms") */
+    transitionSlow?: string;
+    /** Default easing function (default: "cubic-bezier(0.4, 0, 0.2, 1)") */
+    transitionEasing?: string;
+    /** Focus ring width (default: "2px") */
+    focusRingWidth?: string;
+    /** Focus ring offset (default: "2px") */
+    focusRingOffset?: string;
+}
+/**
+ * Complete theme tokens structure
+ *
+ * Contains all customizable values for a theme:
+ * - colors: Required light and dark mode color palettes
+ * - typography: Optional font customization
+ * - spacing: Optional spacing/radius customization
+ * - effects: Optional shadows/transitions customization
+ */
+interface ThemeTokens {
+    /** Light and dark mode color palettes (required) */
+    colors: {
+        /** Light mode color palette */
+        light: ColorPalette;
+        /** Dark mode color palette */
+        dark: ColorPalette;
+    };
+    /** Typography customization (optional) */
+    typography?: Typography;
+    /** Spacing and radius customization (optional) */
+    spacing?: Spacing;
+    /** Shadow and transition customization (optional) */
+    effects?: Effects;
+}
+/**
+ * Custom font definition for themes that include custom fonts
+ */
+interface FontDefinition {
+    /** Font family name */
+    family: string;
+    /** Font source URL or relative path */
+    src: string;
+    /** Font weight (e.g., "400", "700", "400 700") */
+    weight?: string;
+    /** Font style (e.g., "normal", "italic") */
+    style?: string;
+    /** Font display strategy */
+    display?: 'auto' | 'block' | 'swap' | 'fallback' | 'optional';
+}
+/**
+ * Loaded font with binary data (for self-contained themes)
+ */
+interface EmbeddedFont {
+    /** Font family name */
+    family: string;
+    /** Font weight */
+    weight: string;
+    /** Font style */
+    style?: string;
+    /** Base64-encoded font data or data URL */
+    data: string;
+    /** MIME type of the font */
+    mimeType?: string;
+}
+/**
+ * Theme plugin metadata for UI display and identification
+ */
+interface ThemeMetadata {
+    /** Unique theme identifier (lowercase, hyphens allowed) */
+    themeId: string;
+    /** Human-readable display name */
+    displayName: string;
+    /** Theme description */
+    description?: string;
+    /** Theme author */
+    author?: string | {
+        name: string;
+        email?: string;
+        url?: string;
+    };
+    /** Whether this theme provides dark mode support */
+    supportsDarkMode: boolean;
+    /** Theme tags for categorization */
+    tags?: string[];
+    /** Base64-encoded preview image or path */
+    previewImage?: string;
+}
+/**
+ * Main Theme Plugin Interface
+ *
+ * Plugins implementing this interface can be dynamically loaded
+ * by Quilltap to provide custom theming.
+ *
+ * Self-contained themes export all data directly in the plugin object,
+ * with no file system dependencies after module load.
+ *
+ * @example
+ * ```typescript
+ * import type { ThemePlugin } from '@quilltap/plugin-types';
+ *
+ * export const plugin: ThemePlugin = {
+ *   metadata: {
+ *     themeId: 'my-theme',
+ *     displayName: 'My Custom Theme',
+ *     description: 'A beautiful custom theme',
+ *     supportsDarkMode: true,
+ *     tags: ['dark', 'minimal'],
+ *   },
+ *   tokens: {
+ *     colors: {
+ *       light: {
+ *         background: 'hsl(0 0% 100%)',
+ *         foreground: 'hsl(222.2 84% 4.9%)',
+ *         // ... all required colors
+ *       },
+ *       dark: {
+ *         background: 'hsl(222.2 84% 4.9%)',
+ *         foreground: 'hsl(210 40% 98%)',
+ *         // ... all required colors
+ *       },
+ *     },
+ *     typography: {
+ *       fontSans: '"Custom Font", system-ui, sans-serif',
+ *     },
+ *   },
+ *   cssOverrides: `
+ *     .qt-button-primary {
+ *       border-radius: 9999px;
+ *     }
+ *   `,
+ *   fonts: [
+ *     { family: 'Custom Font', weight: '400', data: 'base64...' },
+ *   ],
+ * };
+ * ```
+ */
+interface ThemePlugin {
+    /** Theme metadata for UI display and identification */
+    metadata: ThemeMetadata;
+    /** Theme design tokens (colors, typography, spacing, effects) */
+    tokens: ThemeTokens;
+    /**
+     * Optional CSS overrides for component-level customization (Tier 3)
+     * This CSS is injected when the theme is active
+     */
+    cssOverrides?: string;
+    /**
+     * Optional embedded fonts
+     * Base64-encoded font data for fully self-contained themes
+     */
+    fonts?: EmbeddedFont[];
+    /**
+     * Optional method for dynamic token generation
+     * Called when color mode changes, allows computed theme values
+     * @param mode Current color mode ('light' | 'dark')
+     */
+    getTokensForMode?: (mode: 'light' | 'dark') => ThemeTokens;
+    /**
+     * Optional initialization function
+     * Called when the theme is loaded
+     */
+    initialize?: () => void | Promise<void>;
+}
+/**
+ * Standard export type for theme plugins
+ */
+interface ThemePluginExport {
+    /** The theme plugin instance */
+    plugin: ThemePlugin;
+}
+
+export type { AttachmentSupport as A, CheapModelConfig as C, EmbeddingModelInfo as E, FontDefinition as F, ImageGenerationModelInfo as I, LLMProviderPlugin as L, ModelInfo as M, ProviderMetadata as P, Spacing as S, ToolFormatType as T, ProviderConfigRequirements as a, ProviderCapabilities as b, ImageProviderConstraints as c, IconProps as d, ProviderPluginExport as e, MessageFormatSupport as f, PluginCapability as g, PluginCategory as h, PluginStatus as i, PluginAuthor as j, PluginCompatibility as k, ProviderConfig as l, PluginPermissions as m, PluginManifest as n, InstalledPluginInfo as o, ColorPalette as p, Typography as q, Effects as r, ThemeTokens as s, EmbeddedFont as t, ThemeMetadata as u, ThemePlugin as v, ThemePluginExport as w };