@stacksjs/stx 0.2.0 → 0.2.3

package/dist/hot-reload.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Generate the hot reload client script to inject into HTML
+ */
+export declare function generateHotReloadScript(wsPort: number, options?: HotReloadOptions): string;
+/**
+ * Inject hot reload script into HTML content
+ */
+export declare function injectHotReload(html: string, wsPort: number, options?: HotReloadOptions): string;
+/**
+ * Determine if a file change should trigger a CSS-only update
+ */
+export declare function isCssOnlyChange(filename: string): boolean;
+/**
+ * Determine if a file change should trigger a reload
+ */
+export declare function shouldReloadOnChange(filename: string): boolean;
+/**
+ * Determine if a file should be ignored
+ */
+export declare function shouldIgnoreFile(filename: string): boolean;
+/**
+ * Get or create the global HMR server instance
+ */
+export declare function getHmrServer(options?: HotReloadOptions): HotReloadServer;
+/**
+ * Stop and clear the global HMR server
+ */
+export declare function stopHmrServer(): void;
+/**
+ * Hot Reload Module
+ *
+ * Provides WebSocket-based hot module reload (HMR) for the stx dev server.
+ * When template files change, connected browsers automatically refresh.
+ *
+ * ## Features
+ *
+ * - WebSocket server for real-time browser communication
+ * - Client script injection into HTML
+ * - Full page reload on template changes
+ * - CSS-only updates without full reload (when possible)
+ * - Connection status overlay
+ * - Automatic reconnection on disconnect
+ *
+ * ## Usage
+ *
+ * The hot reload is automatically enabled when using `stx dev` or `serveStxFile()`.
+ * No additional configuration needed.
+ *
+ * ## Architecture
+ *
+ * ```
+ * File System Watch → HMR Server → WebSocket → Browser Client → Reload
+ * ```
+ */
+// =============================================================================
+// Types
+// =============================================================================
+export declare interface HotReloadOptions {
+  wsPort?: number
+  showOverlay?: boolean
+  reconnectInterval?: number
+  maxReconnectAttempts?: number
+  verbose?: boolean
+}
+export declare interface HotReloadMessage {
+  type: 'reload' | 'css-update' | 'connected' | 'error'
+  path?: string
+  content?: string
+  timestamp?: number
+}
+/**
+ * Hot Reload Server
+ *
+ * Manages WebSocket connections and broadcasts reload messages to browsers.
+ */
+export declare class HotReloadServer {
+  private clients: Set<WebSocketClient>;
+  private server: ReturnType<typeof Bun.serve> | null;
+  private options: Required<HotReloadOptions>;
+  constructor(options?: HotReloadOptions);
+  start(port?: number): number;
+  stop(): void;
+  broadcast(message: HotReloadMessage): void;
+  reload(filePath?: string): void;
+  updateCss(filePath: string, content?: string): void;
+  error(message: string): void;
+}

package/dist/hydration-runtime.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Generate the unified hydration bootstrap script.
+ *
+ * This replaces the per-island inline scripts with a single runtime
+ * that reads data-strategy attributes and sets up appropriate triggers.
+ */
+export declare function generateHydrationBootstrap(): string;
+/**
+ * Generate a component manifest script block that registers
+ * all discovered island component names with their import paths.
+ *
+ * @param islands - Map of component name to import path
+ */
+export declare function generateComponentManifest(islands: Map<string, string>): string;
+/**
+ * Extract component name from inner content of an island.
+ * Looks for PascalCase or kebab-case component tags.
+ */
+export declare function extractComponentName(content: string): string | null;
+/**
+ * Extract bound props from component content.
+ * Parses :prop="value" bindings.
+ */
+export declare function extractBoundProps(content: string, context: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Unified Hydration Runtime for Islands Architecture
+ *
+ * Replaces the per-strategy inline scripts with a single runtime that handles
+ * all hydration strategies. Injected once per page when islands are present.
+ *
+ * The runtime:
+ * 1. Component registry — maps names to dynamic imports
+ * 2. hydrateIsland(element) — loads component, reads props, calls hydrate/mount
+ * 3. Strategy dispatcher — sets up triggers per data-strategy attribute
+ * 4. initIslands() — processes all .stx-island:not(.hydrated) on DOMContentLoaded
+ *
+ * @module hydration-runtime
+ */
+// ============================================================================
+// Types
+// ============================================================================
+export declare interface IslandMeta {
+  id: string
+  component: string
+  strategy: string
+  props: Record<string, unknown>
+}

package/dist/hydration.d.ts

@@ -0,0 +1,161 @@
+/**
+ * Serialize state for client hydration
+ * Called during server-side rendering
+ */
+export declare function serializeState(state: Partial<HydrationState>): string;
+/**
+ * Generate the state injection script for server-rendered HTML
+ */
+export declare function generateStateScript(state: Partial<HydrationState>): string;
+/**
+ * Generate event bindings data attribute
+ */
+export declare function generateEventBindings(events: EventBinding[]): string;
+/**
+ * Extract and parse state from server-rendered HTML
+ */
+export declare function extractState(): HydrationState | null;
+/**
+ * Generate the hydration runtime script for embedding in HTML
+ */
+export declare function generateHydrationScript(state?: Partial<HydrationState>): string;
+/**
+ * Get or create the hydration runtime
+ */
+export declare function getHydrationRuntime(options?: HydrationOptions): HydrationRuntime;
+/**
+ * Start hydration (convenience function)
+ */
+export declare function hydrate(options?: HydrationOptions): Promise<void>;
+/**
+ * Generate hydration CSS
+ */
+export declare function generateHydrationCSS(): string;
+/**
+ * STX Hydration Runtime
+ *
+ * Comprehensive client-side hydration system that bridges server-rendered
+ * HTML with client-side interactivity. Similar to React's hydrateRoot or
+ * Vue's createSSRApp.
+ *
+ * ## Features
+ *
+ * - Full page hydration with state restoration
+ * - Selective/partial hydration (islands architecture)
+ * - Event handler binding from server-rendered HTML
+ * - Integration with stx reactivity system
+ * - Seamless SPA router integration
+ * - Progressive enhancement support
+ * - Error boundaries for hydration failures
+ *
+ * ## Usage
+ *
+ * Server-side (stx template):
+ * ```html
+ * <script>
+ * const count = 0
+ * const user = { name: 'Alice' }
+ * </script>
+ *
+ * <button @click="count++">Count: {{ count }}</button>
+ * <p>Hello, {{ user.name }}</p>
+ * ```
+ *
+ * The framework automatically:
+ * 1. Renders HTML on server
+ * 2. Serializes state and embeds in HTML
+ * 3. Client loads, hydrates, binds events
+ * 4. Page becomes interactive
+ *
+ * @module hydration
+ */
+// =============================================================================
+// Types
+// =============================================================================
+export declare interface HydrationState {
+  refs: Record<string, unknown>
+  reactive: Record<string, unknown>
+  props: Record<string, unknown>
+  routeParams: Record<string, string>
+  stores: Record<string, unknown>
+  meta: {
+    title?: string
+    description?: string
+    url?: string
+  }
+  timestamp: number
+  checksum?: string
+}
+export declare interface HydrationOptions {
+  root?: string | HTMLElement
+  strict?: boolean
+  onHydrating?: () => void
+  onHydrated?: () => void
+  onError?: (error: Error) => void
+  performance?: boolean
+  timeout?: number
+}
+export declare interface EventBinding {
+  type: string
+  handler: string
+  modifiers?: string[]
+  preventDefault?: boolean
+  stopPropagation?: boolean
+}
+export declare interface ComponentHydrationConfig {
+  id: string
+  name: string
+  strategy: 'eager' | 'lazy' | 'idle' | 'visible' | 'interaction'
+  props: Record<string, unknown>
+  events: EventBinding[]
+}
+/**
+ * Main hydration class
+ */
+export declare class HydrationRuntime {
+  private state: HydrationState | null;
+  private options: Required<HydrationOptions>;
+  private root: HTMLElement | null;
+  private isHydrated: any;
+  private pendingComponents: Map<string, ComponentHydrationConfig>;
+  private hydratedComponents: Set<string>;
+  constructor(options?: HydrationOptions);
+  hydrate(): Promise<void>;
+  private runHydration(): Promise<void>;
+  private restoreGlobalState(): void;
+  private hydrateComponents(): Promise<void>;
+  private hydrateComponent(el: HTMLElement, config: ComponentHydrationConfig): Promise<void>;
+  private restoreComponentState(el: HTMLElement, state: unknown): void;
+  private setupVisibleHydration(el: HTMLElement, config: ComponentHydrationConfig): void;
+  private setupIdleHydration(el: HTMLElement, config: ComponentHydrationConfig): void;
+  private setupInteractionHydration(el: HTMLElement, config: ComponentHydrationConfig): void;
+  private bindEventHandlers(): void;
+  private bindElementEvents(el: HTMLElement): void;
+  private bindDirectiveEvents(): void;
+  private parseModifiers(el: HTMLElement, eventType: string): string[];
+  private bindSingleEvent(el: HTMLElement, event: EventBinding): void;
+  private resolveHandler(handlerStr: string): ((e: Event) => void) | null;
+  private bindComponentEvents(el: HTMLElement): void;
+  private initializeComponentReactivity(el: HTMLElement, config: ComponentHydrationConfig): void;
+  private initializeReactiveBindings(): void;
+  private getTextNodesWithExpressions(root: HTMLElement): Array<{
+    node: Text
+    expressions: string[]
+  }>;
+  private setupTextNodeBinding(node: Text, expression: string): void;
+  private setupAttributeBinding(el: HTMLElement, attr: string, expression: string): void;
+  private setupReactiveBinding(el: HTMLElement, expression: string): void;
+  private setupRouterIntegration(): void;
+  getState(): HydrationState | null;
+  hydrateById(componentId: string): Promise<void>;
+}
+export default {
+  HydrationRuntime,
+  serializeState,
+  generateStateScript,
+  generateHydrationScript,
+  generateHydrationCSS,
+  extractState,
+  getHydrationRuntime,
+  hydrate,
+};

package/dist/i18n.d.ts

@@ -1,10 +1,220 @@
 import type { I18nConfig, StxOptions } from './types';
 /**
- * Load a translation file
+ * Clear the translation cache
+ * @param locale - Optional locale to clear. If not provided, clears all.
+ */
+export declare function clearTranslationCache(locale?: string): void;
+/**
+ * Get translation cache statistics
+ */
+export declare function getTranslationCacheStats(): {
+  size: number
+  locales: string[]
+  entries: Array<{ locale: string, loadedAt: Date, keyCount: number }>
+};
+/**
+ * Get the loading state for a locale
+ *
+ * @param locale - The locale to check
+ * @returns The current loading state
+ */
+export declare function getLoadingState(locale: string): LoadingState;
+/**
+ * Check if a locale is currently being loaded
+ *
+ * @param locale - The locale to check
+ * @returns True if the locale is currently loading
+ */
+export declare function isLoading(locale: string): boolean;
+/**
+ * Check if a locale has been loaded (cached)
+ *
+ * @param locale - The locale to check
+ * @returns True if the locale is loaded and cached
+ */
+export declare function isLoaded(locale: string): boolean;
+/**
+ * Preload translations for specified locales in the background.
+ * This is non-blocking and returns immediately.
+ *
+ * @param config - Preload configuration
+ * @param options - stx options with i18n configuration
+ * @returns A promise that resolves when all preloading is complete
+ *
+ * @example
+ * // Preload common locales in parallel
+ * preloadTranslations({
+ *   locales: ['en', 'es', 'fr', 'de'],
+ *   parallel: true,
+ *   onLocaleLoaded: (locale) => console.log(`${locale} ready`),
+ *   onComplete: () => console.log('All translations loaded')
+ * }, options)
+ *
+ * @example
+ * // Preload with priority (user's locale first)
+ * preloadTranslations({
+ *   locales: ['en', 'es', 'fr', 'de'],
+ *   parallel: false,
+ *   priority: { 'es': 10, 'en': 5 }, // Spanish first, then English
+ * }, options)
+ */
+export declare function preloadTranslations(config: PreloadConfig, options: StxOptions): Promise<void>;
+/**
+ * Start preloading translations in the background without blocking.
+ * This function returns immediately and loads in the background.
+ *
+ * @param config - Preload configuration
+ * @param options - stx options with i18n configuration
+ *
+ * @example
+ * // Fire and forget background preloading
+ * preloadTranslationsBackground({
+ *   locales: ['en', 'es', 'fr'],
+ *   parallel: true
+ * }, options)
+ * // Execution continues immediately
+ */
+export declare function preloadTranslationsBackground(config: PreloadConfig, options: StxOptions): void;
+/**
+ * Lazy load a translation file with deduplication.
+ * If a load is already in progress for this locale, returns the existing promise.
+ * This prevents multiple simultaneous loads of the same locale.
+ *
+ * @param locale - Locale code (e.g., 'en', 'fr', 'de')
+ * @param options - stx options with i18n configuration
+ * @returns Promise resolving to translation dictionary
+ *
+ * @example
+ * // Multiple calls during loading period share the same promise
+ * const p1 = loadTranslationLazy('en', options)
+ * const p2 = loadTranslationLazy('en', options)
+ * // p1 === p2 (same promise instance)
+ */
+export declare function loadTranslationLazy(locale: string, options: StxOptions): Promise<Record<string, any>>;
+/**
+ * Get a translation synchronously if already cached, otherwise return undefined.
+ * This is useful for non-blocking render patterns where you want to show
+ * a fallback while translations load.
+ *
+ * @param locale - Locale code
+ * @returns Cached translations or undefined if not loaded
+ *
+ * @example
+ * const translations = getTranslationSync('en')
+ * if (translations) {
+ *   // Use translations
+ * } else {
+ *   // Show loading state or fallback
+ *   loadTranslationLazy('en', options).then(handleLoaded)
+ * }
+ */
+export declare function getTranslationSync(locale: string): Record<string, any> | undefined;
+/**
+ * Get translation with automatic loading.
+ * Returns cached translations immediately if available,
+ * otherwise loads them and returns.
+ *
+ * This is the recommended async API for most use cases.
+ *
+ * @param locale - Locale code
+ * @param options - stx options
+ * @returns Promise resolving to translations
+ */
+export declare function getTranslationAsync(locale: string, options: StxOptions): Promise<Record<string, any>>;
+/**
+ * Wait for a locale to finish loading.
+ * Useful when you've started a background preload and need to wait for it.
+ *
+ * @param locale - Locale to wait for
+ * @param timeoutMs - Optional timeout in milliseconds
+ * @returns Promise that resolves when loaded, or rejects on timeout/error
+ *
+ * @example
+ * preloadTranslationsBackground({ locales: ['en', 'es'] }, options)
+ * // ... later
+ * await waitForLocale('en', 5000) // Wait up to 5 seconds
+ */
+export declare function waitForLocale(locale: string, timeoutMs?: number): Promise<Record<string, any>>;
+/**
+ * Get all currently loading locales
+ *
+ * @returns Array of locale codes currently being loaded
+ */
+export declare function getLoadingLocales(): string[];
+/**
+ * Cancel pending translation loads (clears pending state).
+ * Note: This doesn't actually abort HTTP requests, but clears tracking state.
+ *
+ * @param locale - Optional locale to cancel. If not provided, cancels all.
+ */
+export declare function cancelPendingLoads(locale?: string): void;
+/**
+ * Load a translation file.
+ *
+ * This is the main entry point for loading translations. It uses lazy loading
+ * with deduplication internally, so multiple calls for the same locale will
+ * share the same promise.
+ *
+ * For more control over loading behavior, see:
+ * - `loadTranslationLazy()` - Explicit lazy loading with deduplication
+ * - `preloadTranslations()` - Preload multiple locales
+ * - `getTranslationSync()` - Get cached translations without loading
+ * - `getTranslationAsync()` - Get with automatic loading
+ *
+ * @param locale - Locale code (e.g., 'en', 'fr', 'de')
+ * @param options - stx options with i18n configuration
+ * @returns Translation dictionary
  */
 export declare function loadTranslation(locale: string, options: StxOptions): Promise<Record<string, any>>;
 /**
- * Get a translation by key
+ * ICU MessageFormat parser and formatter
+ *
+ * Supports:
+ * - Simple replacement: {name}
+ * - Plural: {count, plural, =0{none} one{# item} other{# items}}
+ * - Select: {gender, select, male{He} female{She} other{They}}
+ * - SelectOrdinal: {pos, selectordinal, one{#st} two{#nd} few{#rd} other{#th}}
+ * - Number formatting: {amount, number}
+ * - Date formatting: {date, date, short|medium|long|full}
+ *
+ * @example
+ * formatICU('{count, plural, =0{No items} one{# item} other{# items}}', { count: 5 })
+ * // => '5 items'
+ *
+ * @example
+ * formatICU('{gender, select, male{He} female{She} other{They}} liked this', { gender: 'female' })
+ * // => 'She liked this'
+ */
+export declare function formatICU(message: string, params?: Record<string, unknown>): string;
+/**
+ * Check if a message uses ICU format
+ */
+export declare function isICUFormat(message: string): boolean;
+/**
+ * Get a translation by key with parameter replacement and pluralization.
+ *
+ * Supports both Laravel-style (:param, |plural) and ICU MessageFormat.
+ *
+ * @param key - Dot-notation key (e.g., 'messages.welcome')
+ * @param translations - Translation dictionary
+ * @param fallbackToKey - Return key if translation not found
+ * @param params - Parameters for replacement (use 'count' for pluralization)
+ * @returns The translated string
+ *
+ * @example
+ * // Simple parameter replacement
+ * getTranslation('greeting', { greeting: 'Hello :name' }, true, { name: 'John' })
+ * // => 'Hello John'
+ *
+ * @example
+ * // Pluralization (Laravel-style)
+ * getTranslation('items', { items: 'One item|:count items' }, true, { count: 5 })
+ * // => '5 items'
+ *
+ * @example
+ * // ICU MessageFormat
+ * getTranslation('items', { items: '{count, plural, one{# item} other{# items}}' }, true, { count: 5 })
+ * // => '5 items'
  */
 export declare function getTranslation(key: string, translations: Record<string, any>, fallbackToKey?: boolean, params?: Record<string, any>): string;
 /**
@@ -15,5 +225,31 @@ export declare function processTranslateDirective(template: string, context: Rec
  * Create a translation filter for expressions
  */
 export declare function createTranslateFilter(translations: Record<string, any>, fallbackToKey?: boolean): (value: string, params?: Record<string, any>) => string;
+// =============================================================================
+// Configuration
+// =============================================================================
 // Default i18n configuration
-export declare const defaultI18nConfig: I18nConfig;
+export declare const defaultI18nConfig: I18nConfig;
+/**
+ * Pending load tracking for deduplication
+ */
+declare interface PendingLoad {
+  promise: Promise<Record<string, any>>
+  state: LoadingState
+  error?: Error
+}
+/**
+ * Preload configuration
+ */
+export declare interface PreloadConfig {
+  locales: string[]
+  parallel?: boolean
+  priority?: Record<string, number>
+  onLocaleLoaded?: (locale: string) => void
+  onComplete?: () => void
+  onError?: (locale: string, error: Error) => void
+}
+/**
+ * Loading state for async translation loading
+ */
+declare type LoadingState = 'idle' | 'loading' | 'loaded' | 'error'

package/dist/image-optimization/build-plugin.d.ts

@@ -0,0 +1,53 @@
+import { type ImageOptions,  } from './processor';
+import type { BuildPlugin } from '../production-build';
+/**
+ * Create the image optimization build plugin
+ */
+export declare function createImagePlugin(options?: ImageBuildOptions): BuildPlugin;
+/**
+ * Optimize a single image
+ */
+export declare function optimizeImage(inputPath: string, outputDir: string, options?: ImageOptions): Promise<ProcessedImage>;
+/**
+ * Optimize all images in a directory
+ */
+export declare function optimizeDirectory(inputDir: string, outputDir: string, options?: ImageBuildOptions): Promise<{
+  processed: ProcessedImage[]
+  stats: ImageBuildContext['stats']
+}>;
+/**
+ * Generate image manifest for build
+ */
+export declare function generateImageManifest(images: ProcessedImage[]): Record<string, { variants: ImageVariant[]; placeholder?: string }>;
+/**
+ * Write image manifest to file
+ */
+export declare function writeImageManifest(images: ProcessedImage[], outputPath: string): Promise<void>;
+// ============================================================================
+// Types
+// ============================================================================
+export declare interface ImageBuildOptions {
+  inputDirs?: string[]
+  outputDir?: string
+  baseUrl?: string
+  defaults?: ImageOptions
+  cache?: boolean
+  cacheDir?: string
+  concurrency?: number
+  referencedOnly?: boolean
+  formats?: ImageFormat[]
+  widths?: number[]
+  quality?: number
+  placeholder?: 'blur' | 'dominant-color' | 'none'
+  verbose?: boolean
+}
+export declare interface ImageBuildContext {
+  imageReferences: Set<string>
+  processedImages: Map<string, ProcessedImage>
+  stats: {
+    totalImages: number
+    optimizedImages: number
+    savedBytes: number
+    variants: number
+  }
+}

package/dist/image-optimization/component.d.ts

@@ -0,0 +1,46 @@
+import { type ImageFormat,  } from './processor';
+/**
+ * Render an optimized <Image> component
+ */
+export declare function renderImageComponent(props: ImageComponentProps, context?: ImageRenderContext): ImageRenderResult;
+/**
+ * Parse Image component from template
+ */
+export declare function parseImageComponent(content: string): ImageComponentProps | null;
+/**
+ * Process Image components in template content
+ */
+export declare function processImageComponents(content: string, processor: (props: ImageComponentProps) => Promise<ImageRenderResult>): Promise<{ html: string; preloadLinks: string[]; styles: string[] }>;
+// ============================================================================
+// Types
+// ============================================================================
+export declare interface ImageComponentProps {
+  src: string
+  alt: string
+  width?: number | string
+  height?: number | string
+  sizes?: string | Record<string, string>
+  loading?: 'lazy' | 'eager'
+  priority?: boolean
+  quality?: number
+  placeholder?: 'blur' | 'color' | 'none'
+  formats?: ImageFormat[]
+  widths?: number[]
+  class?: string
+  style?: string
+  decoding?: 'sync' | 'async' | 'auto'
+  fetchpriority?: 'high' | 'low' | 'auto'
+  objectFit?: 'contain' | 'cover' | 'fill' | 'none' | 'scale-down'
+  objectPosition?: string
+}
+export declare interface ImageRenderContext {
+  processedImage?: ProcessedImage
+  variants?: ImageVariant[]
+  optimize?: boolean
+  isDev?: boolean
+}
+export declare interface ImageRenderResult {
+  html: string
+  preloadLink?: string
+  placeholderCss?: string
+}

package/dist/image-optimization/directive.d.ts

@@ -0,0 +1,30 @@
+import { type ImageFormat,  } from './processor';
+import type { CustomDirective } from '../types';
+/**
+ * Clear the image cache
+ */
+export declare function clearImageCache(): void;
+/**
+ * Create the @image directive
+ */
+export declare function createImageDirective(): CustomDirective;
+/**
+ * The @image directive instance
+ */
+export declare const imageDirective: unknown;
+// ============================================================================
+// Types
+// ============================================================================
+export declare interface ImageDirectiveOptions {
+  width?: number
+  height?: number
+  quality?: number
+  lazy?: boolean
+  formats?: ImageFormat[]
+  widths?: number[]
+  sizes?: string
+  class?: string
+  style?: string
+  priority?: boolean
+  placeholder?: 'blur' | 'color' | 'none'
+}