@stacksjs/stx 0.1.16 → 0.2.3

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

@@ -0,0 +1,86 @@
+/**
+ * Default image configuration
+ */
+export declare const defaultImageConfig: ImageConfig;
+/**
+ * Image optimization configuration for stx.config.ts
+ */
+export declare interface ImageConfig {
+  enabled?: boolean
+  widths?: number[]
+  formats?: ('webp' | 'avif' | 'jpeg' | 'png')[]
+  quality?: number
+  devOptimize?: boolean
+  cacheDir?: string
+  placeholder?: 'blur' | 'dominant-color' | 'none'
+  inputDirs?: string[]
+  outputDir?: string
+  baseUrl?: string
+}
+export {
+  // Core processing
+  processImage,
+  getImageMetadata,
+  isSharpAvailable,
+
+  // HTML helpers
+  generateSrcSet,
+  generateSizes,
+  getFallbackVariant,
+  groupVariantsByFormat,
+
+  // Utilities
+  isImageFile,
+  getMimeType,
+  getTotalSize,
+  formatSize,
+
+  // Error class
+  ImageProcessingError,
+
+  // Constants
+  DEFAULT_WIDTHS,
+  DEFAULT_FORMATS,
+  DEFAULT_QUALITY,
+
+  // Types
+  type ImageOptions,
+  type ImageFormat,
+  type ProcessedImage,
+  type ImageVariant,
+  type ImageMetadata,
+} from './processor';
+export {
+  // Rendering
+  renderImageComponent,
+  parseImageComponent,
+  processImageComponents,
+
+  // Types
+  type ImageComponentProps,
+  type ImageRenderContext,
+  type ImageRenderResult,
+} from './component';
+export {
+  // Directive
+  imageDirective,
+  createImageDirective,
+  clearImageCache,
+
+  // Types
+  type ImageDirectiveOptions,
+} from './directive';
+export {
+  // Plugin
+  createImagePlugin,
+
+  // Standalone functions
+  optimizeImage,
+  optimizeDirectory,
+  generateImageManifest,
+  writeImageManifest,
+
+  // Types
+  type ImageBuildOptions,
+  type ImageBuildContext,
+} from './build-plugin';

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

@@ -0,0 +1,112 @@
+import path from 'node:path';
+/**
+ * Check if sharp is available
+ */
+export declare function isSharpAvailable(): Promise<boolean>;
+/**
+ * Process an image and generate responsive variants
+ */
+export declare function processImage(input: string | Buffer, options?: ImageOptions): Promise<ProcessedImage>;
+/**
+ * Get image metadata
+ */
+export declare function getImageMetadata(input: Buffer | string): Promise<ImageMetadata>;
+/**
+ * Generate srcset attribute from variants
+ */
+export declare function generateSrcSet(variants: ImageVariant[], format?: ImageFormat): string;
+/**
+ * Generate sizes attribute
+ */
+export declare function generateSizes(breakpoints?: Record<string, string>): string;
+/**
+ * Get best fallback variant (middle resolution JPEG)
+ */
+export declare function getFallbackVariant(variants: ImageVariant[]): ImageVariant | undefined;
+/**
+ * Group variants by format
+ */
+export declare function groupVariantsByFormat(variants: ImageVariant[]): Map<ImageFormat, ImageVariant[]>;
+/**
+ * Check if file is an image
+ */
+export declare function isImageFile(filePath: string): boolean;
+/**
+ * Get MIME type for format
+ */
+export declare function getMimeType(format: ImageFormat): string;
+/**
+ * Calculate total size of variants
+ */
+export declare function getTotalSize(variants: ImageVariant[]): number;
+/**
+ * Format file size for display
+ */
+export declare function formatSize(bytes: number): string;
+// ============================================================================
+// Constants
+// ============================================================================
+export declare const DEFAULT_WIDTHS: readonly [320, 640, 768, 1024, 1280, 1536, 1920];
+export declare const DEFAULT_FORMATS: ImageFormat[];
+export declare const DEFAULT_QUALITY: 80;
+// ============================================================================
+// Types
+// ============================================================================
+export declare interface ImageOptions {
+  widths?: number[]
+  formats?: ImageFormat[]
+  quality?: number
+  fit?: 'cover' | 'contain' | 'fill' | 'inside' | 'outside'
+  placeholder?: 'blur' | 'dominant-color' | 'none'
+  outputDir?: string
+  baseUrl?: string
+}
+export declare interface ProcessedImage {
+  src: string
+  variants: ImageVariant[]
+  placeholder?: string
+  width: number
+  height: number
+  aspectRatio: number
+  hash: string
+}
+export declare interface ImageVariant {
+  path: string
+  url: string
+  width: number
+  height: number
+  format: ImageFormat
+  size: number
+}
+export declare interface ImageMetadata {
+  width: number
+  height: number
+  format: string
+  hasAlpha?: boolean
+}
+export type ImageFormat = 'webp' | 'avif' | 'jpeg' | 'png'
+// ============================================================================
+// Sharp Integration
+// ============================================================================
+declare type SharpInstance = {
+  metadata(): Promise<ImageMetadata>
+  resize(width: number, height?: number, options?: { fit?: string }): SharpInstance
+  webp(options?: { quality?: number }): SharpInstance
+  avif(options?: { quality?: number }): SharpInstance
+  jpeg(options?: { quality?: number }): SharpInstance
+  png(options?: { quality?: number }): SharpInstance
+  toBuffer(): Promise<Buffer>
+  blur(sigma: number): SharpInstance
+  toFormat(format: string, options?: { quality?: number }): SharpInstance
+}
+declare type SharpModule = {
+  (input: Buffer | string): SharpInstance
+  default?: (input: Buffer | string) => SharpInstance
+}
+// ============================================================================
+// Error Handling
+// ============================================================================
+export declare class ImageProcessingError extends Error {
+  code: string;
+  constructor(message: string, code: string);
+}

package/dist/includes.d.ts

@@ -1,24 +1,109 @@
+import { LRUCache } from './performance-utils';
 import type { StxOptions } from './types';
 /**
  * Clear the @once store - useful for testing and resetting state
+ *
+ * IMPORTANT: In server environments, call this at the start of each request
+ * to prevent @once content from being incorrectly skipped across requests.
+ *
+ * Alternatively, use request-scoped tracking by setting `context.__onceStore = new Set()`
+ * before processing templates. The processor will use context.__onceStore if available.
+ *
+ * @example
+ * ```typescript
+ * // Option 1: Clear global store per request
+ * app.use((req, res, next) => {
+ *   clearOnceStore()
+ *   next()
+ * })
+ *
+ * // Option 2: Use request-scoped store (preferred)
+ * const context = {
+ *   __onceStore: new Set<string>(),
+ *   ...otherData
+ * }
+ * await processDirectives(template, context, filePath, options)
+ * ```
  */
 export declare function clearOnceStore(): void;
 /**
- * Process @include and @partial directives
+ * Process @include, @partial, @includeIf, @includeWhen, @includeUnless,
+ * @includeFirst, and @once directives.
+ *
+ * This is the main function for include processing. It handles all include
+ * variants and the @once directive for deduplication.
+ *
+ * @param template - The template string to process
+ * @param context - Template context with variables
+ * @param filePath - Path to the current template file
+ * @param options - STX processing options
+ * @param dependencies - Set to track included file dependencies (for caching)
+ * @returns The processed template with includes resolved
+ *
+ * @example
+ * ```typescript
+ * const deps = new Set<string>()
+ * const result = await processIncludes(
+ *   '@include("header") <main>Content</main> @include("footer")',
+ *   { title: 'My Page' },
+ *   '/app/views/home.stx',
+ *   options,
+ *   deps
+ * )
+ * // deps now contains paths to header.stx and footer.stx
+ * ```
  */
-export declare function processIncludes(template: string, context: Record<string, any>, filePath: string, options: StxOptions, dependencies: Set<string>): Promise<string>;
+export declare function processIncludes(template: string, context: Record<string, any>, filePath: string, options: StxOptions, dependencies: Set<string>, includeStack?: Set<string>): Promise<string>;
 /**
- * Stack related functions for @push, @stack, @prepend directives
- */
-/**
- * Process @push and @prepend directives to collect content
+ * Process @push and @prepend directives to collect content into named stacks.
+ *
+ * This function extracts stack content and removes the directives from output.
+ * The collected content is stored in the `stacks` object for later rendering.
+ *
+ * @param template - The template string to process
+ * @param stacks - Object to collect stack content (mutated)
+ * @returns Template with @push/@prepend directives removed
+ *
+ * @example
+ * ```typescript
+ * const stacks: Record<string, string[]> = {}
+ * const result = processStackPushDirectives(`
+ *   @push('scripts')
+ *     <script src="app.js"></script>
+ *   @endpush
+ *   <div>Content</div>
+ * `, stacks)
+ * // result = '\n  <div>Content</div>\n'
+ * // stacks = { scripts: ['<script src="app.js"></script>'] }
+ * ```
  */
 export declare function processStackPushDirectives(template: string, stacks: Record<string, string[]>): string;
 /**
- * Process @stack directives by replacing them with their content
+ * Process @stack directives by replacing them with collected stack content.
+ *
+ * This should be called AFTER `processStackPushDirectives` has collected
+ * all @push and @prepend content.
+ *
+ * @param template - The template string with @stack directives
+ * @param stacks - Object containing collected stack content
+ * @returns Template with @stack directives replaced by their content
+ *
+ * @example
+ * ```typescript
+ * const stacks = {
+ *   scripts: ['<script src="a.js"></script>', '<script src="b.js"></script>'],
+ *   styles: ['<link rel="stylesheet" href="app.css">']
+ * }
+ * const result = processStackReplacements(`
+ *   <head>@stack('styles')</head>
+ *   <body>...@stack('scripts')</body>
+ * `, stacks)
+ * ```
  */
 export declare function processStackReplacements(template: string, stacks: Record<string, string[]>): string;
-// Cache for partials to avoid repeated file reads
-export declare const partialsCache: Map<string, string>;
+// Cache for partials to avoid repeated file reads (LRU with max 500 entries)
+export declare const partialsCache: LRUCache<string, string>;
 // Global store to track what has been included via @once
+// WARNING: This persists across requests in long-running servers!
+// Use clearOnceStore() at the start of each request, or use request-scoped tracking via context.__onceStore
 export declare const onceStore: Set<string>;

package/dist/index.d.ts

@@ -1,30 +1,90 @@
+export type { StxComponentInstance, EmitFn } from './composition-api';
+export type { VNode } from './jsx-runtime';
+export type { StxApp, StxAppPlugin, StxPluginInput, StxAppConfig } from './app';
+export { type BuildResult } from './build-optimizer';
+export { type ComponentInstance } from './reactivity';
+export { type HydrationOptions } from './hydration';
+export { type CookieOptions } from './route-middleware';
+export { formatSize, getTotalSize } from './deploy';
+export { type ImageRenderResult, type ImageVariant, type ProcessedImage, clearImageCache, getFallbackVariant, getMimeType, groupVariantsByFormat, optimizeImage, processImage } from './image-optimization';
+export { type AnalysisResult } from './analyzer';
+export { type AnalyzeOptions, type ChunkInfo } from './production-build';
+export { fileExists } from './utils';
+export { type StreamingConfig } from './types';
+export { type Middleware } from './ssr';
+export * from './reactivity';
+export * from './head';
+export * from './route-middleware';
+export * from './runtime';
+export * from './forms';
+export * from './env';
 export * from './a11y';
+export * from './analytics';
 export * from './analyzer';
 export * from './animation';
 export * from './assets';
+export * from './async-components';
 export * from './auth';
+export * from './build-optimizer';
 export * from './caching';
 export * from './components';
 export * from './config';
+export * from './csp';
 export * from './custom-directives';
+export * from './defer';
+export * from './deploy';
 export * from './dev-server';
+export * from './directive-api';
 export * from './docs';
+export * from './edge-runtime';
 export * from './error-handling';
+export * from './events';
 export * from './expressions';
 export * from './formatter';
-export * from './forms';
+export * from './heatmap';
+export * from './hot-reload';
 export * from './i18n';
 export * from './includes';
 export * from './init';
+export * from './interactive';
+export * from './keep-alive';
 export * from './loops';
 export * from './markdown';
 export * from './middleware';
+export * from './parser';
 export * from './process';
+export * from './production-build';
 export * from './release';
+export * from './router';
+export * from './scaffolding';
 export * from './seo';
 export * from './serve';
 export * from './streaming';
-export * from './types';
-export * from './utils';
+export * from './suspense';
+export * from './teleport';
+export * from './transitions';
+export * from './type-checker';
 export * from './web-components';
+export * from './virtual-scrolling';
+export * from './partial-hydration';
+export * from './hydration-runtime';
+export * from './client';
+export * from './loading-indicator';
+export * from './reactive-bindings';
+export * from './client-script';
+export * from './component-hmr';
+export * from './hydration';
+export * from './ssr';
+export * from './image-optimization';
+export * from './media';
+export * from './build-views';
+export * from './signals';
+export * from './vue-template';
+export { provide, inject, setGlobalProvide, defineEmits, defineExpose, nextTick, onErrorCaptured, handleError, useSlots, useAttrs, createProvideContext, generateCompositionRuntime } from './composition-api';
+export { jsx, jsxs, jsxDEV, Fragment, renderToString, renderToStream, renderToDOM, Show, For, Portal, h } from './jsx-runtime';
+export { createApp as createStxApp } from './app';
+export * from './dynamic-components';
+export * from './utils';
+export * from './slots';
+export * from './types';
 export default {};