@useavalon/avalon 0.1.23 → 0.1.25

package/dist/src/vite-plugin/integration-activator.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Integration Activator for Avalon Vite Plugin
+ *
+ * This module handles the activation of framework integrations based on
+ * the plugin configuration. It validates integration names and loads
+ * the appropriate integration packages.
+ */
+import type { IntegrationName, ResolvedAvalonConfig } from "./types.ts";
+/**
+ * Valid integration names that can be activated
+ * This array is used for validation and error messages
+ */
+export declare const VALID_INTEGRATION_NAMES: readonly IntegrationName[];
+/**
+ * Check if a string is a valid integration name
+ *
+ * @param name - The name to validate
+ * @returns True if the name is a valid IntegrationName
+ */
+export declare function isValidIntegrationName(name: string): name is IntegrationName;
+/**
+ * Activates the specified integrations
+ *
+ * Uses the existing integration loader and registry to load and activate
+ * framework integrations based on the configuration.
+ *
+ * @param config - The resolved Avalon configuration
+ * @param activeIntegrations - Set to track which integrations have been activated
+ * @throws IntegrationError if an invalid integration name is provided or loading fails
+ *
+ * @example
+ * ```ts
+ * const activeIntegrations = new Set<IntegrationName>();
+ * await activateIntegrations(resolvedConfig, activeIntegrations);
+ * // activeIntegrations now contains all successfully loaded integrations
+ * ```
+ */
+export declare function activateIntegrations(config: ResolvedAvalonConfig, activeIntegrations: Set<IntegrationName>): Promise<void>;
+/**
+ * Activate a single integration by name
+ *
+ * @param name - The integration name to activate
+ * @param activeIntegrations - Set to track which integrations have been activated
+ * @param verbose - Whether to log activation messages
+ * @returns True if the integration was activated, false if already active
+ * @throws IntegrationError if the name is invalid or loading fails
+ */
+export declare function activateSingleIntegration(name: string, activeIntegrations: Set<IntegrationName>, _verbose?: boolean): Promise<boolean>;

package/dist/src/vite-plugin/island-sidecar-plugin.d.ts

@@ -0,0 +1,17 @@
+import type { Plugin } from "vite";
+export interface SidecarPluginOptions {
+    /** Whether to log verbose output */
+    verbose?: boolean;
+}
+/**
+ * Check tsconfig.json for `allowArbitraryExtensions` and warn if missing.
+ */
+export declare function checkTsConfigForArbitraryExtensions(projectRoot: string): Promise<void>;
+/**
+ * Vite plugin that auto-generates `.d.[ext].ts` sidecar declaration files
+ * for non-React/Preact components when they are used as islands.
+ *
+ * Sidecars are generated on-demand when component files are loaded,
+ * rather than scanning a fixed directory at startup.
+ */
+export declare function islandSidecarPlugin(options?: SidecarPluginOptions): Plugin;

package/dist/src/vite-plugin/module-discovery.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Module Discovery for Modular Architecture
+ *
+ * Discovers pages and layouts within feature modules for file-based routing.
+ * Supports co-located architecture where each module contains its own pages/layouts.
+ */
+import type { ResolvedModulesConfig } from "./types.ts";
+/**
+ * Discovered module with its pages and layouts directories
+ */
+export interface DiscoveredModule {
+    /** Module name (folder name) */
+    name: string;
+    /** Absolute path to the module directory */
+    path: string;
+    /** Absolute path to pages directory (if exists) */
+    pagesDir: string | null;
+    /** Absolute path to layouts directory (if exists) */
+    layoutsDir: string | null;
+    /** Route prefix derived from module name */
+    routePrefix: string;
+}
+/**
+ * Result of module discovery
+ */
+export interface ModuleDiscoveryResult {
+    /** All discovered modules */
+    modules: DiscoveredModule[];
+    /** All page directories (for route discovery) */
+    pageDirs: Array<{
+        dir: string;
+        prefix: string;
+    }>;
+    /** All layout directories */
+    layoutDirs: Array<{
+        dir: string;
+        prefix: string;
+    }>;
+}
+/**
+ * Discover all modules within the modules directory
+ *
+ * @param modulesConfig - Resolved modules configuration
+ * @param projectRoot - Project root directory
+ * @returns Discovery result with modules, page dirs, and layout dirs
+ */
+export declare function discoverModules(modulesConfig: ResolvedModulesConfig, projectRoot: string): Promise<ModuleDiscoveryResult>;
+/**
+ * Get all page directories including both traditional and modular
+ *
+ * @param pagesDir - Traditional pages directory
+ * @param modulesConfig - Modules configuration (if any)
+ * @param projectRoot - Project root
+ * @returns Array of page directories with their route prefixes
+ */
+export declare function getAllPageDirs(pagesDir: string, modulesConfig: ResolvedModulesConfig | null, projectRoot: string): Promise<Array<{
+    dir: string;
+    prefix: string;
+}>>;
+/**
+ * Get all layout directories including both traditional and modular
+ */
+export declare function getAllLayoutDirs(layoutsDir: string, modulesConfig: ResolvedModulesConfig | null, projectRoot: string): Promise<Array<{
+    dir: string;
+    prefix: string;
+}>>;

package/dist/src/vite-plugin/nitro-integration.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Nitro Integration Module for Avalon Vite Plugin
+ *
+ * Provides coordination between Avalon's Vite plugin and Nitro:
+ * - API routes: Auto-discovered by Nitro from `api/` directory
+ * - Page routes: Virtual module for SSR page component discovery
+ * - Middleware: Auto-discovered by Nitro from `middleware/` directory
+ */
+import type { Plugin, ViteDevServer } from 'vite';
+import type { ResolvedAvalonConfig } from './types.ts';
+import { type AvalonNitroConfig, type NitroConfigOutput } from '../nitro/config.ts';
+export declare const VIRTUAL_MODULE_IDS: {
+    readonly PAGE_ROUTES: "virtual:avalon/page-routes";
+    readonly ISLAND_MANIFEST: "virtual:avalon/island-manifest";
+    readonly RUNTIME_CONFIG: "virtual:avalon/runtime-config";
+    readonly CONFIG: "virtual:avalon/config";
+};
+export declare const RESOLVED_VIRTUAL_IDS: {
+    readonly PAGE_ROUTES: string;
+    readonly ISLAND_MANIFEST: string;
+    readonly RUNTIME_CONFIG: string;
+    readonly CONFIG: string;
+};
+export interface NitroIntegrationResult {
+    nitroOptions: NitroConfigOutput;
+    plugins: Plugin[];
+}
+export interface NitroCoordinationPluginOptions {
+    avalonConfig: ResolvedAvalonConfig;
+    nitroConfig: AvalonNitroConfig;
+    verbose?: boolean;
+}
+/**
+ * Creates the Nitro integration for Avalon — configuration, virtual modules,
+ * build plugins, and SSR coordination.
+ *
+ * Uses the Nitro v3 Vite plugin from `nitro/vite` for server route discovery,
+ * SSR rendering pipeline, and Rolldown-optimized bundling.
+ */
+export declare function createNitroIntegration(avalonConfig: ResolvedAvalonConfig, nitroConfig?: AvalonNitroConfig): NitroIntegrationResult;
+/**
+ * Coordination plugin: stores config/server refs, sets up SSR middleware and HMR,
+ * and prewarms core infrastructure modules (fire-and-forget).
+ */
+export declare function createNitroCoordinationPlugin(options: NitroCoordinationPluginOptions): Plugin;
+/**
+ * Virtual modules plugin — page routes, island manifest, runtime config.
+ */
+export declare function createVirtualModulesPlugin(options: NitroCoordinationPluginOptions): Plugin;
+export declare function generateConfigModule(avalonConfig: ResolvedAvalonConfig, nitroConfig: AvalonNitroConfig): string;
+export declare function getViteDevServer(): ViteDevServer | undefined;
+export declare function getAvalonConfig(): ResolvedAvalonConfig | undefined;
+export declare function isDevelopmentMode(): boolean;
+declare global {
+    var __avalonLayoutResolver: unknown;
+}

package/dist/src/vite-plugin/plugin.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Avalon Vite Plugin
+ *
+ * This module provides the main `avalon()` function that creates a unified Vite plugin
+ * for the Avalon framework. It handles configuration resolution, integration activation,
+ * Nitro server integration, and wires up all the necessary Vite hooks.
+ *
+ * ISLAND DETECTION:
+ * Islands are detected by usage - any component used with an `island` prop in pages
+ * or layouts is automatically treated as an island. No fixed islands directory required.
+ */
+import type { Plugin, PluginOption, ViteDevServer } from 'vite';
+import type { AvalonPluginConfig, IntegrationName, ResolvedAvalonConfig } from './types.ts';
+import type { NitroConfigOutput } from '../nitro/config.ts';
+declare global {
+    var __avalonConfig: ResolvedAvalonConfig | undefined;
+    var __viteDevServer: ViteDevServer | undefined;
+    var __nitroConfig: NitroConfigOutput | undefined;
+}
+/**
+ * Collects Vite plugins from all activated integrations.
+ *
+ * This function iterates through the activated integrations and calls their
+ * vitePlugin() method if implemented. The returned plugins are collected and
+ * flattened into a single array.
+ *
+ * Plugin ordering is handled to ensure correct application:
+ * - Lit plugins come first (DOM shim requirement)
+ * - Other framework plugins follow
+ *
+ * @param activeIntegrations - Set of activated integration names
+ * @param verbose - Whether to log detailed information
+ * @returns Promise resolving to an array of Vite plugins from integrations
+ */
+export declare function collectIntegrationPlugins(activeIntegrations: Set<IntegrationName>, verbose?: boolean): Promise<Plugin[]>;
+/**
+ * Creates the Avalon Vite plugin array
+ *
+ * @param config - Avalon configuration options
+ * @returns A promise that resolves to an array of Vite plugins that handle all Avalon functionality.
+ *          Returns PluginOption[] to avoid TypeScript's excessive stack depth issues
+ *          when comparing Plugin<any> arrays in Vite 8's complex type system.
+ */
+export declare function avalon(config?: AvalonPluginConfig): Promise<PluginOption[]>;
+export declare function getResolvedConfig(): ResolvedAvalonConfig | undefined;
+export declare function getPagesDir(): string;
+export declare function getLayoutsDir(): string;
+export declare function getNitroConfig(): NitroConfigOutput | undefined;
+export declare function isNitroEnabled(): boolean;
+export type { AvalonPluginConfig, IntegrationName, ResolvedAvalonConfig, ImageConfig, ResolvedImageConfig, } from './types.ts';
+export type { AvalonNitroConfig, NitroConfigOutput } from '../nitro/config.ts';

package/dist/src/vite-plugin/types.d.ts

@@ -0,0 +1,281 @@
+/**
+ * Vite Plugin Types for Avalon
+ *
+ * CONFIG PATH: Vite plugin runtime
+ * These types define the inline configuration passed to `avalon()` in
+ * `vite.config.ts`. The `resolveConfig()` function in `vite-plugin/config.ts`
+ * merges user options against `DEFAULT_CONFIG` to produce a `ResolvedAvalonConfig`.
+ *
+ * This path uses `IntegrationName[]` (simple string array) for integrations.
+ *
+ * There is a separate CLI config path (`schemas/integration-config.ts` →
+ * `config-loader.ts` → `startup.ts` → `cli.ts`) that reads `avalon.config.ts`
+ * from disk and uses `IntegrationConfigEntry[]` (objects with name/enabled/options).
+ * That path is NOT used during Vite plugin startup.
+ */
+import type { AvalonNitroConfig } from "../nitro/config.ts";
+/**
+ * Image optimization configuration
+ */
+export interface ImageConfig {
+    /**
+     * Enable image optimization via vite-imagetools
+     * @default true
+     */
+    enabled?: boolean;
+    /**
+     * Default image format for optimized images
+     * @default "webp"
+     */
+    defaultFormat?: "webp" | "avif" | "jpg" | "png";
+    /**
+     * Default image quality (1-100)
+     * @default 80
+     */
+    quality?: number;
+    /**
+     * Breakpoint widths for srcset generation
+     * @default [200, 400, 600, 800, 1200]
+     */
+    widths?: number[];
+    /**
+     * Whether to strip EXIF and other metadata from images
+     * @default true
+     */
+    removeMetadata?: boolean;
+    /**
+     * File patterns to include for image processing
+     * @default /^[^?]+\.(heif|avif|jpeg|jpg|png|tiff|webp|gif)(\?.*)?$/
+     */
+    include?: string | RegExp | (string | RegExp)[];
+    /**
+     * File patterns to exclude from image processing
+     * @default "public/**\/*"
+     */
+    exclude?: string | RegExp | (string | RegExp)[];
+}
+/**
+ * Resolved image optimization configuration
+ */
+export interface ResolvedImageConfig {
+    enabled: boolean;
+    defaultFormat: "webp" | "avif" | "jpg" | "png";
+    quality: number;
+    widths: number[];
+    removeMetadata: boolean;
+    include: string | RegExp | (string | RegExp)[];
+    exclude: string | RegExp | (string | RegExp)[];
+}
+/**
+ * Supported integration names
+ * These correspond to the @useavalon/* packages
+ */
+export type IntegrationName = "react" | "preact" | "vue" | "svelte" | "solid" | "lit" | "qwik";
+/**
+ * MDX configuration options
+ */
+export interface MDXConfig {
+    /**
+     * JSX import source for MDX files
+     * @default "preact"
+     */
+    jsxImportSource?: string;
+    /**
+     * Enable syntax highlighting for code blocks
+     * @default true
+     */
+    syntaxHighlighting?: boolean;
+    /**
+     * Custom remark plugins
+     */
+    remarkPlugins?: unknown[];
+    /**
+     * Custom rehype plugins
+     */
+    rehypePlugins?: unknown[];
+}
+/**
+ * Modular architecture configuration
+ * Enables co-located pages/layouts within feature modules
+ */
+export interface ModulesConfig {
+    /**
+     * Directory containing feature modules
+     * @example "app/modules"
+     */
+    dir: string;
+    /**
+     * Name of the pages directory within each module
+     * @default "pages"
+     */
+    pagesDirName?: string;
+    /**
+     * Name of the layouts directory within each module
+     * @default "layouts"
+     */
+    layoutsDirName?: string;
+}
+/**
+ * Configuration options for the Avalon Vite plugin
+ */
+export interface AvalonPluginConfig {
+    /**
+     * Directory containing page components for file-system routing
+     * @default "src/pages"
+     */
+    pagesDir?: string;
+    /**
+     * Directory containing layout components
+     * @default "src/layouts"
+     */
+    layoutsDir?: string;
+    /**
+     * Modular architecture configuration
+     * When set, discovers pages and layouts within feature modules
+     * Can be a string (just the dir) or full config object
+     *
+     * @example
+     * ```ts
+     * // Simple - uses default 'pages' and 'layouts' folder names
+     * modules: 'app/modules'
+     *
+     * // Full config - customize folder names
+     * modules: {
+     *   dir: 'app/modules',
+     *   pagesDirName: 'views',
+     *   layoutsDirName: 'layouts',
+     * }
+     * ```
+     */
+    modules?: string | ModulesConfig;
+    /**
+     * Framework integrations to activate
+     * Simply list the framework names - the integration packages handle the rest
+     * @example ["react", "svelte", "lit"]
+     */
+    integrations?: IntegrationName[];
+    /**
+     * MDX processing configuration
+     */
+    mdx?: MDXConfig;
+    /**
+     * Image optimization configuration
+     * When enabled, Avalon auto-injects vite-imagetools with sensible defaults.
+     * Set to `false` to disable, or pass an object to customize.
+     *
+     * @default { enabled: true }
+     *
+     * @example
+     * ```ts
+     * // Use defaults (webp, quality 80, standard breakpoints)
+     * image: true
+     *
+     * // Customize
+     * image: {
+     *   defaultFormat: 'avif',
+     *   quality: 90,
+     *   widths: [320, 640, 1024, 1920],
+     * }
+     *
+     * // Disable
+     * image: false
+     * ```
+     */
+    image?: boolean | ImageConfig;
+    /**
+     * Nitro server runtime configuration
+     * When provided, enables Nitro integration for universal deployment
+     *
+     * @example
+     * ```ts
+     * nitro: {
+     *   preset: 'vercel',
+     *   streaming: true,
+     *   routeRules: {
+     *     '/api/**': { cors: true },
+     *     '/static/**': { cache: { maxAge: 86400 } },
+     *   },
+     * }
+     * ```
+     */
+    nitro?: AvalonNitroConfig;
+    /**
+     * Enable verbose logging during development
+     * @default false
+     */
+    verbose?: boolean;
+    /**
+     * Auto-discover integrations based on component file extensions
+     * When true, Avalon will automatically activate integrations
+     * based on the components you use, even if not listed in integrations
+     * @default true
+     */
+    autoDiscoverIntegrations?: boolean;
+    /**
+     * Validate integrations on startup
+     * When true, Avalon will check that all integrations
+     * implement the required interface correctly
+     * @default true
+     */
+    validateIntegrations?: boolean;
+    /**
+     * Show warnings for integration issues
+     * When true, Avalon will log warnings for non-critical
+     * integration problems
+     * @default true
+     */
+    showWarnings?: boolean;
+    /**
+     * Enable lazy loading of integration Vite plugins
+     * When true (default), Avalon will only load Vite plugins for integrations
+     * that are actually used in your project, significantly improving cold start time.
+     *
+     * The lazy loading works by:
+     * 1. Scanning the islands directory to discover which frameworks are used
+     * 2. Only loading Vite plugins for those frameworks at startup
+     * 3. Loading additional plugins on-demand if new frameworks are encountered
+     *
+     * Set to false to load all configured integrations at startup (slower but predictable).
+     * @default true
+     */
+    lazyIntegrations?: boolean;
+}
+/**
+ * Fully resolved MDX configuration with defaults applied
+ */
+export interface ResolvedMDXConfig {
+    jsxImportSource: string;
+    syntaxHighlighting: boolean;
+    remarkPlugins: unknown[];
+    rehypePlugins: unknown[];
+}
+/**
+ * Resolved modular architecture configuration
+ */
+export interface ResolvedModulesConfig {
+    dir: string;
+    pagesDirName: string;
+    layoutsDirName: string;
+}
+/**
+ * Fully resolved configuration with defaults applied
+ */
+export interface ResolvedAvalonConfig {
+    pagesDir: string;
+    layoutsDir: string;
+    modules: ResolvedModulesConfig | null;
+    integrations: IntegrationName[];
+    mdx: ResolvedMDXConfig;
+    image: ResolvedImageConfig;
+    verbose: boolean;
+    autoDiscoverIntegrations: boolean;
+    validateIntegrations: boolean;
+    showWarnings: boolean;
+    lazyIntegrations: boolean;
+    isDev: boolean;
+}
+/**
+ * Re-export Nitro configuration types for convenience
+ */
+export type { AvalonNitroConfig } from "../nitro/config.ts";
+export type { CacheOptions, RouteRule, NitroConfigOutput, AvalonRuntimeConfig, StaticAssetsConfig, } from "../nitro/config.ts";

package/dist/src/vite-plugin/validation.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Integration Validation for Avalon Vite Plugin
+ *
+ * This module provides validation functions to ensure that framework integrations
+ * implement the required interface correctly. Validation can be enabled via the
+ * `validateIntegrations` configuration option.
+ */
+import type { IntegrationName } from "./types.ts";
+/**
+ * Result of validating a single integration
+ */
+export interface ValidationResult {
+    /** The integration name that was validated */
+    integration: IntegrationName;
+    /** Whether the integration passed all required checks */
+    valid: boolean;
+    /** Critical errors that prevent the integration from working */
+    errors: string[];
+    /** Non-critical warnings about the integration */
+    warnings: string[];
+}
+/**
+ * Result of validating all active integrations
+ */
+export interface ValidationSummary {
+    /** Whether all integrations passed validation */
+    allValid: boolean;
+    /** Individual validation results for each integration */
+    results: ValidationResult[];
+    /** Total number of errors across all integrations */
+    totalErrors: number;
+    /** Total number of warnings across all integrations */
+    totalWarnings: number;
+}
+/**
+ * Validate that an integration implements the required interface
+ *
+ * Checks for the following required properties:
+ * - name: string - Unique name of the integration
+ * - version: string - Version of the integration package
+ * - render: function - Server-side rendering function
+ * - getHydrationScript: function - Returns hydration script for client
+ * - config: function - Returns integration configuration
+ *
+ * Also checks optional properties if present:
+ * - vitePlugin: function (if provided)
+ *
+ * @param integration - The integration object to validate
+ * @returns ValidationResult with errors and warnings
+ *
+ * @example
+ * ```ts
+ * const result = validateIntegration(myIntegration);
+ * if (!result.valid) {
+ *   console.error('Integration validation failed:', result.errors);
+ * }
+ * ```
+ */
+export declare function validateIntegration(integration: unknown): ValidationResult;
+/**
+ * Validate all active integrations in the registry
+ *
+ * Iterates through all integrations that have been activated and validates
+ * each one against the required interface.
+ *
+ * @param activeIntegrations - Set of integration names that have been activated
+ * @param showWarnings - Whether to include warnings in the results
+ * @returns ValidationSummary with results for all integrations
+ *
+ * @example
+ * ```ts
+ * const activeIntegrations = new Set<IntegrationName>(['react', 'vue']);
+ * const summary = validateActiveIntegrations(activeIntegrations, true);
+ * if (!summary.allValid) {
+ *   console.error(`${summary.totalErrors} validation errors found`);
+ * }
+ * ```
+ */
+export declare function validateActiveIntegrations(activeIntegrations: Set<IntegrationName>, showWarnings?: boolean): ValidationSummary;
+/**
+ * Format validation results for console output
+ *
+ * @param summary - The validation summary to format
+ * @returns Formatted string for console output
+ */
+export declare function formatValidationResults(summary: ValidationSummary): string;
+/**
+ * Validate a single integration by name from the registry
+ *
+ * @param name - The integration name to validate
+ * @returns ValidationResult or null if integration not found
+ */
+export declare function validateIntegrationByName(name: IntegrationName): ValidationResult | null;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@useavalon/avalon",
-	"version": "0.1.23",
+	"version": "0.1.25",
 	"description": "Multi-framework islands architecture for the modern web",
 	"license": "MIT",
 	"type": "module",
@@ -36,14 +36,38 @@
 		"postpublish": "bun run scripts/postpublish.ts"
 	},
 	"exports": {
-		".": "./dist/mod.js",
-		"./client": "./dist/src/client/components.js",
-		"./client/hmr": "./dist/src/client/framework-adapter.js",
-		"./islands/framework-detection": "./dist/src/islands/framework-detection.js",
-		"./middleware": "./dist/src/middleware/index.js",
-		"./nitro/renderer": "./dist/src/nitro/renderer.js",
-		"./nitro/types": "./dist/src/nitro/types.js",
-		"./nitro/config": "./dist/src/nitro/config.js",
+		".": {
+			"types": "./dist/mod.d.ts",
+			"default": "./dist/mod.js"
+		},
+		"./client": {
+			"types": "./dist/src/client/components.d.ts",
+			"default": "./dist/src/client/components.js"
+		},
+		"./client/hmr": {
+			"types": "./dist/src/client/framework-adapter.d.ts",
+			"default": "./dist/src/client/framework-adapter.js"
+		},
+		"./islands/framework-detection": {
+			"types": "./dist/src/islands/framework-detection.d.ts",
+			"default": "./dist/src/islands/framework-detection.js"
+		},
+		"./middleware": {
+			"types": "./dist/src/middleware/index.d.ts",
+			"default": "./dist/src/middleware/index.js"
+		},
+		"./nitro/renderer": {
+			"types": "./dist/src/nitro/renderer.d.ts",
+			"default": "./dist/src/nitro/renderer.js"
+		},
+		"./nitro/types": {
+			"types": "./dist/src/nitro/types.d.ts",
+			"default": "./dist/src/nitro/types.js"
+		},
+		"./nitro/config": {
+			"types": "./dist/src/nitro/config.d.ts",
+			"default": "./dist/src/nitro/config.js"
+		},
 		"./types/island-jsx": "./dist/src/types/island-jsx.d.ts",
 		"./types": "./dist/src/types/index.d.ts"
 	},