@useavalon/avalon 0.1.12 → 0.1.13

package/mod.ts

@@ -0,0 +1,302 @@
+// === Core Avalon + Vite Architecture ===
+
+// Vite Plugin - unified configuration API
+export {
+	avalon,
+	getResolvedConfig,
+	getPagesDir,
+	getLayoutsDir,
+	getNitroConfig,
+	isNitroEnabled,
+} from './src/vite-plugin/plugin.ts';
+export type {
+	AvalonPluginConfig,
+	IntegrationName,
+	ResolvedAvalonConfig,
+	MDXConfig,
+	ResolvedMDXConfig,
+	AvalonNitroConfig,
+	CacheOptions,
+	RouteRule,
+	NitroConfigOutput,
+	AvalonRuntimeConfig,
+} from './src/vite-plugin/types.ts';
+
+// Nitro Integration - virtual modules and coordination
+export {
+	createNitroIntegration,
+	createNitroCoordinationPlugin,
+	createVirtualModulesPlugin,
+	getViteDevServer,
+	getAvalonConfig,
+	isDevelopmentMode,
+	VIRTUAL_MODULE_IDS,
+	RESOLVED_VIRTUAL_IDS,
+} from './src/vite-plugin/nitro-integration.ts';
+export type { NitroIntegrationResult, NitroCoordinationPluginOptions } from './src/vite-plugin/nitro-integration.ts';
+
+// Main exports
+export { renderToHtml } from './src/render/ssr.ts';
+
+// Universal Island component (single function auto-detects framework)
+export { default as Island, renderIsland, type IslandProps } from './src/islands/island.tsx';
+
+// Island utilities
+export {
+	addSvelteSSRCSS,
+	getSvelteSSRCSS,
+	getSvelteSSRCSSForHead,
+	getSvelteSSRCSSStats,
+	getSvelteComponentCSS,
+	clearSvelteComponentCSS,
+	generateComponentScopeId,
+} from './src/islands/css-utils.ts';
+export { detectFramework, detectFrameworkFromSrc, resolveIslandPath } from './src/islands/framework-detection.ts';
+export { analyzeComponentFile, renderComponentSSROnly } from './src/islands/component-analysis.ts';
+export type { Framework, RenderParams, SvelteSSRCSSEntry } from './src/islands/types.ts';
+
+// Island render cache utilities
+export {
+	clearCache,
+	clearIslandCache,
+	invalidateCacheForPath,
+	invalidateCacheForFile,
+	getCacheStats,
+	logCacheStats,
+	configureCache,
+	getCacheConfig,
+} from './src/islands/render-cache.ts';
+export type { CacheConfig as IslandCacheConfig, CacheStats as IslandCacheStats } from './src/islands/render-cache.ts';
+
+// Island Discovery Utilities (optional - for advanced use cases)
+// Note: Islands are detected by usage (island prop), not by directory.
+// These utilities are provided for tooling that needs to scan component files.
+export {
+	// Scanner functions
+	discoverIslandDirectories,
+	discoverIslandsInDirectory,
+	discoverAllIslands,
+	isIslandsDirectory,
+	getDefaultIslandsPath,
+	hasDefaultIslandsDirectory,
+	getQualifiedIslandName,
+	parseQualifiedIslandName,
+	// Registry
+	IslandRegistry,
+	createIslandRegistry,
+	// Resolver
+	IslandResolver,
+	createIslandResolver,
+	// Validator
+	IslandValidator,
+	createIslandValidator,
+	validateAllIslands,
+	formatValidationError,
+	formatValidationWarning,
+	formatCircularDependency,
+	formatValidationResult,
+	// Watcher
+	IslandWatcher,
+	createIslandWatcher,
+	// Type utilities
+	ISLAND_FILE_EXTENSIONS,
+	DEFAULT_DISCOVERY_CONFIG,
+	isSupportedIslandExtension,
+} from './src/islands/discovery/index.ts';
+
+// Island Discovery Types
+export type {
+	IslandDirectory,
+	DiscoveredIsland,
+	IslandCollision,
+	IslandChangeEvent,
+	IslandFileExtension,
+	IslandDiscoveryConfig,
+	ResolutionResult,
+	ImportPathOptions,
+	ValidationResult,
+	ValidationError,
+	ValidationWarning,
+	CircularDependency,
+	IslandChangeCallback,
+	IslandWatcherOptions,
+} from './src/islands/discovery/index.ts';
+
+// Integration system
+export {
+	loadIntegration,
+	detectAndLoadIntegration,
+	preloadIntegrations,
+	detectFrameworksFromPageContent,
+	DEFAULT_PRELOAD_FRAMEWORKS,
+} from './src/islands/integration-loader.ts';
+export type { PreloadIntegrationsOptions } from './src/islands/integration-loader.ts';
+export { registry as integrationRegistry } from './src/core/integrations/registry.ts';
+export type {
+	Integration,
+	RenderParams as IntegrationRenderParams,
+	RenderResult,
+	IntegrationConfig,
+} from '@useavalon/core';
+
+// Build utilities
+export { generateIslandManifest, loadIslandManifest, getIslandBundlePath } from './src/build/island-manifest.ts';
+export type {
+	IslandManifest,
+	IslandEntry,
+	ExtendedIslandManifest,
+	ExtendedIslandEntry,
+} from './src/build/island-manifest.ts';
+
+// MDX island transform (auto-wraps island imports in MDX with Island() calls)
+export { mdxIslandTransform } from './src/build/mdx-island-transform.ts';
+export type { MDXIslandTransformOptions } from './src/build/mdx-island-transform.ts';
+
+// Page island transform (auto-wraps island imports in TSX pages when using `island` prop)
+export { pageIslandTransform } from './src/build/page-island-transform.ts';
+export type { PageIslandTransformOptions } from './src/build/page-island-transform.ts';
+
+// Island directive type for the `island` prop
+export type { IslandDirective } from './src/types/island-prop.d.ts';
+export { asIsland } from './src/types/as-island.ts';
+
+// Island type generation
+export { generateIslandTypes, watchAndGenerateTypes } from './src/build/island-types-generator.ts';
+export type { IslandTypeGeneratorOptions, TypeGenerationResult } from './src/build/island-types-generator.ts';
+
+// Build command
+// Note: The build function is only available in the monorepo development environment.
+// End users should use the CLI or Vite build commands directly.
+export async function build(_options?: Record<string, unknown>) {
+	throw new Error(
+		'avalon build() is not available in the published package. Use `vite build` or the Avalon CLI instead.',
+	);
+}
+
+// Middleware system (Nitro-aligned)
+// Note: defineMiddleware removed — use defineHandler from 'nitro/h3' directly.
+// Scoped middleware discovery/execution is Avalon's value-add over Nitro.
+export {
+	discoverScopedMiddleware,
+	executeScopedMiddleware,
+	clearMiddlewareCache,
+	invalidateMiddleware,
+	getMatchingMiddleware,
+	clearDiscoveryCache,
+	hasContextValue,
+	getContextValue,
+	setContextValue,
+	getMiddlewareCacheSize,
+} from './src/middleware/index.ts';
+
+export type {
+	MiddlewareHandler,
+	MiddlewareFileExport,
+	MiddlewareRoute,
+	MiddlewareDiscoveryOptions,
+	MiddlewareExecutorOptions,
+} from './src/middleware/types.ts';
+
+// Layout system - comprehensive export (all layout functionality)
+export * from './src/layout-system.ts';
+
+// Core types
+export type { RenderOptions, MetaTag, ScriptConfig } from './src/schemas/core.ts';
+export type { ApiRoute, ApiMethod } from './src/schemas/api.ts';
+export type { MiddlewareContext } from './src/nitro/middleware-adapter.ts';
+
+// Layout data loading types
+export type { LayoutDataLoadingResult, LayoutDataLoadingOptions } from './src/core/layout/layout-data-loader.ts';
+
+// Enhanced layout resolver types
+export type { EnhancedLayoutResolverOptions } from './src/core/layout/enhanced-layout-resolver.ts';
+
+// Layout cache types (essential only)
+export type { CacheEntry, CacheStats, CacheConfig } from './src/core/layout/layout-cache-manager.ts';
+
+// Layout system types - comprehensive export
+export type {
+	// Core layout types (from hand-written interfaces — proper types, no Zod inference)
+	LayoutProps,
+	LayoutContext,
+	LayoutData,
+	LayoutRoute,
+	LayoutHandler,
+	LayoutDiscoveryOptions,
+	LayoutConfig,
+	RouteInfo,
+	LayoutRule,
+	LayoutLoader,
+	ResolvedLayout,
+	LayoutCache,
+	LayoutErrorInfo
+} from './src/core/layout/layout-types.ts';
+
+export type {
+	// Zod-inferred types for schemas that don't have hand-written equivalents
+	EnhancedLayoutContext,
+
+	// Persistent islands types
+	IslandState,
+	PersistentIslandProps,
+	PersistentIslandContext,
+	IslandStateSaver,
+	IslandStateLoader,
+	IslandStateClearer,
+
+	// Error boundary types
+	LayoutErrorBoundaryProps,
+	ErrorRecoveryStrategy,
+	LayoutErrorHandler,
+	LayoutRetryFunction,
+	LayoutFallbackRenderer,
+
+	// Streaming types
+	StreamingLayoutProps,
+	StreamingComponent,
+	StreamingReadyCheck,
+
+	// Function types
+	LayoutMatcherFunction,
+} from './src/schemas/layout.ts';
+
+// Persistent islands system
+export { IslandPersistence, defaultIslandPersistence } from './src/core/islands/island-persistence.ts';
+export { IslandStateSerializer } from './src/core/islands/island-state-serializer.ts';
+export {
+	createPersistentIslandContext,
+	usePersistentIslandContext,
+	PersistentIslandProvider,
+} from './src/core/islands/persistent-island-context.tsx';
+export { PersistentIsland } from './src/components/PersistentIsland.tsx';
+export { usePersistentState } from './src/core/islands/use-persistent-state.ts';
+
+// Error boundary system
+export { LayoutErrorBoundary } from './src/components/LayoutErrorBoundary.tsx';
+export { LayoutDataErrorBoundary } from './src/components/LayoutDataErrorBoundary.tsx';
+export { IslandErrorBoundary, withIslandErrorBoundary } from './src/components/IslandErrorBoundary.tsx';
+export { StreamingErrorBoundary, withStreamingErrorBoundary } from './src/components/StreamingErrorBoundary.tsx';
+
+// Layout system interfaces
+export type {
+	ILayoutDiscovery,
+	ILayoutMatcher,
+	ILayoutComposer,
+	IIslandPersistence,
+	ILayoutErrorRecovery,
+	ILayoutStreaming,
+	IEnhancedLayoutResolver,
+	ILayoutComponent,
+	IPersistentIslandComponent,
+	ILayoutErrorBoundaryComponent,
+	IStreamingLayoutComponent,
+	LayoutModule,
+	PageModule,
+	LayoutResolutionContext,
+	LayoutPerformanceMetrics,
+	LayoutDebugInfo,
+	LayoutEventType,
+	LayoutEventData,
+	LayoutEventHandler,
+	ILayoutEventEmitter,
+} from './src/types/layout.ts';

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@useavalon/avalon",
-	"version": "0.1.12",
+	"version": "0.1.13",
 	"description": "Multi-framework islands architecture for the modern web",
 	"license": "MIT",
 	"type": "module",
@@ -44,24 +44,16 @@
 		}
 	},
 	"files": [
-		"dist/**/*.js",
-		"dist/**/*.d.ts",
+		"mod.ts",
+		"src/**/*.ts",
+		"src/**/*.tsx",
+		"src/**/*.js",
+		"src/**/*.d.ts",
+		"!src/**/*.test.ts",
+		"!src/**/tests/**",
+		"!src/**/__tests__/**",
 		"README.md"
 	],
-	"publishConfig": {
-		"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/island-jsx": "./dist/src/types/island-jsx.d.ts",
-			"./types": "./dist/src/types/index.d.ts"
-		}
-	},
 	"devDependencies": {
 		"@types/mime-types": "^3.0.1",
 		"oxc-minify": "^0.120.0"

package/src/build/integration-bundler-plugin.ts

@@ -0,0 +1,116 @@
+import type { Plugin } from 'vite';
+import { resolve } from 'node:path';
+import { getOptimizeDepsForIntegrations, getSSRNoExternalForIntegrations } from './integration-config.ts';
+
+export interface IntegrationBundlerOptions {
+	/** Integrations to include in the build */
+	integrations: string[];
+	/** Whether to bundle for SSR */
+	ssr?: boolean;
+}
+
+/**
+ * Vite plugin to bundle integration packages
+ * Ensures integration server and client code is properly bundled
+ */
+export function integrationBundlerPlugin(options: IntegrationBundlerOptions): Plugin {
+	const { integrations, ssr = false } = options;
+	const cwd = process.cwd();
+
+	return {
+		name: 'avalon:integration-bundler',
+		enforce: 'post',
+
+		config(config) {
+			// Add integration entry points to the build
+			const entries: Record<string, string> = {};
+			
+			for (const framework of integrations) {
+				if (ssr) {
+					// SSR build: include server-side integration code
+					entries[`integrations/${framework}/server`] = resolve(
+						cwd,
+						`packages/integrations/${framework}/server/renderer.ts`
+					);
+				} else {
+					// Client build: include client-side integration code
+					entries[`integrations/${framework}/client`] = resolve(
+						cwd,
+						`packages/integrations/${framework}/client/index.ts`
+					);
+				}
+			}
+
+			// Merge with existing rolldown input
+			const existingInput = config.build?.rolldownOptions?.input || {};
+			const mergedInput = typeof existingInput === 'string' 
+				? { main: existingInput, ...entries }
+				: { ...existingInput, ...entries };
+
+			return {
+				build: {
+					rolldownOptions: {
+						input: mergedInput,
+					},
+				},
+			};
+		},
+
+
+	};
+}
+
+/**
+ * Get external dependencies for integration bundling
+ * These should not be bundled but loaded from node_modules
+ */
+export function getIntegrationExternals(framework: string, ssr: boolean) {
+	const externals: string[] = [];
+
+	// Framework-specific externals
+	switch (framework) {
+		case 'preact':
+			if (!ssr) {
+				// Client-side: preact should be bundled for hydration
+				return [];
+			}
+			// SSR: keep preact external if needed
+			externals.push('preact', 'preact/hooks', 'preact-render-to-string');
+			break;
+
+		case 'vue':
+			if (ssr) {
+				// SSR: Vue server renderer should be external
+				externals.push('vue', 'vue/server-renderer', '@vue/server-renderer', '@vue/shared');
+			}
+			break;
+
+		case 'solid':
+			if (ssr) {
+				externals.push('solid-js', 'solid-js/web');
+			}
+			break;
+
+		case 'svelte':
+			if (ssr) {
+				externals.push('svelte', 'svelte/server', 'svelte/compiler', 'svelte/internal');
+			}
+			break;
+	}
+
+	return externals;
+}
+
+/**
+ * Configure optimization for integration dependencies
+ */
+export function getIntegrationOptimizeDeps(integrations: string[]) {
+	return getOptimizeDepsForIntegrations(integrations);
+}
+
+/**
+ * Get SSR noExternal packages for integrations
+ */
+export function getIntegrationSSRNoExternal(integrations: string[]) {
+	return getSSRNoExternalForIntegrations(integrations);
+}

package/src/build/integration-config.ts

@@ -0,0 +1,168 @@
+/**
+ * Integration configuration for build system
+ * Defines how each integration should be bundled and optimized
+ */
+
+export interface IntegrationBuildConfig {
+	/** Framework name */
+	name: string;
+	/** File extensions this integration handles */
+	extensions: string[];
+	/** NPM packages that should be optimized for this integration */
+	optimizeDeps: string[];
+	/** NPM packages that should be external in SSR builds */
+	ssrExternal: string[];
+	/** NPM packages that should NOT be external in SSR builds */
+	ssrNoExternal: string[];
+	/** Whether this integration requires a Vite plugin */
+	requiresPlugin: boolean;
+	/** Plugin package name (if requiresPlugin is true) */
+	pluginPackage?: string;
+}
+
+/**
+ * Build configuration for all supported integrations
+ */
+export const INTEGRATION_BUILD_CONFIGS: Record<string, IntegrationBuildConfig> = {
+	preact: {
+		name: 'preact',
+		extensions: ['.tsx', '.jsx'],
+		optimizeDeps: [
+			'preact',
+			'preact/hooks',
+			'preact/jsx-runtime',
+			'preact/jsx-dev-runtime',
+		],
+		ssrExternal: [],
+		ssrNoExternal: ['preact', 'preact-render-to-string'],
+		requiresPlugin: false,
+	},
+
+	vue: {
+		name: 'vue',
+		extensions: ['.vue'],
+		optimizeDeps: ['vue'],
+		ssrExternal: [],
+		ssrNoExternal: ['vue', '@vue/server-renderer', '@vue/shared'],
+		requiresPlugin: true,
+		pluginPackage: '@vitejs/plugin-vue',
+	},
+
+	solid: {
+		name: 'solid',
+		extensions: ['.tsx', '.jsx'],
+		optimizeDeps: [
+			'solid-js',
+			'solid-js/web',
+			'solid-js/store',
+		],
+		ssrExternal: [],
+		ssrNoExternal: ['solid-js', 'solid-js/web', 'solid-js/store'],
+		requiresPlugin: true,
+		pluginPackage: 'vite-plugin-solid',
+	},
+
+	svelte: {
+		name: 'svelte',
+		extensions: ['.svelte'],
+		optimizeDeps: [
+			'svelte',
+			'svelte/internal',
+			'svelte/store',
+			'svelte/animate',
+			'svelte/easing',
+			'svelte/motion',
+			'svelte/transition',
+		],
+		ssrExternal: [],
+		ssrNoExternal: ['svelte', 'svelte/server', 'svelte/internal', 'svelte/store'],
+		requiresPlugin: true,
+		pluginPackage: '@sveltejs/vite-plugin-svelte',
+	},
+
+	react: {
+		name: 'react',
+		extensions: ['.jsx', '.tsx'],
+		optimizeDeps: [
+			'react',
+			'react/jsx-runtime',
+			'react/jsx-dev-runtime',
+			'react-dom',
+			'react-dom/client',
+		],
+		ssrExternal: [],
+		ssrNoExternal: ['react', 'react-dom', 'react-dom/server'],
+		requiresPlugin: true,
+		pluginPackage: '@vitejs/plugin-react',
+	},
+
+	lit: {
+		name: 'lit',
+		extensions: ['.ts', '.js'],
+		optimizeDeps: [
+			'lit',
+			'lit/decorators.js',
+			'lit/directives/class-map.js',
+			'lit/directives/style-map.js',
+			'@lit/reactive-element',
+		],
+		ssrExternal: [],
+		ssrNoExternal: ['lit', '@lit-labs/ssr', '@lit/reactive-element', 'lit-html'],
+		requiresPlugin: false,
+	},
+};
+
+/**
+ * Get build configuration for a specific integration
+ */
+export function getIntegrationBuildConfig(framework: string) {
+	return INTEGRATION_BUILD_CONFIGS[framework];
+}
+
+/**
+ * Get all optimize deps for given integrations
+ */
+export function getOptimizeDepsForIntegrations(integrations: string[]) {
+	const deps = new Set<string>();
+	
+	for (const integration of integrations) {
+		const config = INTEGRATION_BUILD_CONFIGS[integration];
+		if (config) {
+			config.optimizeDeps.forEach(dep => deps.add(dep));
+		}
+	}
+	
+	return Array.from(deps);
+}
+
+/**
+ * Get SSR noExternal packages for given integrations
+ */
+export function getSSRNoExternalForIntegrations(integrations: string[]) {
+	const packages = new Set<string>();
+	
+	for (const integration of integrations) {
+		const config = INTEGRATION_BUILD_CONFIGS[integration];
+		if (config) {
+			config.ssrNoExternal.forEach(pkg => packages.add(pkg));
+		}
+	}
+	
+	return Array.from(packages);
+}
+
+/**
+ * Check if an integration requires a Vite plugin
+ */
+export function integrationRequiresPlugin(framework: string) {
+	const config = INTEGRATION_BUILD_CONFIGS[framework];
+	return config?.requiresPlugin ?? false;
+}
+
+/**
+ * Get plugin package name for an integration
+ */
+export function getIntegrationPluginPackage(framework: string) {
+	const config = INTEGRATION_BUILD_CONFIGS[framework];
+	return config?.pluginPackage;
+}