@stacksjs/stx 0.2.154 → 0.2.156

package/dist/heatmap.d.ts

@@ -1,25 +1,4 @@
 import type { CustomDirective, StxOptions } from './types';
-/**
- * Generate heatmap tracking script based on configuration
- */
-export declare function generateHeatmapScript(options: StxOptions): string;
-/**
- * Inject heatmap script into HTML
- * Scripts are injected just before </body> for optimal loading
- */
-export declare function injectHeatmap(html: string, options: StxOptions): string;
-/**
- * Create a heatmap aggregator instance
- */
-export declare function createHeatmapAggregator(): HeatmapAggregator;
-/**
- * Default heatmap configuration
- */
-export declare const defaultHeatmapConfig: HeatmapConfig;
-/**
- * Custom @heatmap directive for explicit placement
- */
-export declare const heatmapDirective: CustomDirective;
 /**
  * Heatmap Module
  *
@@ -54,73 +33,174 @@ export declare const heatmapDirective: CustomDirective;
 /**
  * Heatmap tracking configuration
  */
-export declare interface HeatmapConfig {
-  enabled: boolean
-  trackMouse?: boolean
-  trackClicks?: boolean
-  trackScroll?: boolean
-  samplingRate?: number
-  honorDnt?: boolean
-  endpoint?: string
-  batchSize?: number
-  maxDataPoints?: number
-  sessionTimeout?: number
-  persistData?: boolean
-  storagePrefix?: string
-  captureAttributes?: string[]
-  ignoreSelectors?: string[]
-  zones?: HeatmapZone[]
-  debugOverlay?: boolean
-  minViewportWidth?: number
-  maxViewportWidth?: number
+export interface HeatmapConfig {
+    /** Enable heatmap tracking */
+    enabled: boolean;
+    /** Track mouse movements */
+    trackMouse?: boolean;
+    /** Track click events */
+    trackClicks?: boolean;
+    /** Track scroll depth */
+    trackScroll?: boolean;
+    /** Sampling rate in milliseconds for mouse tracking (default: 100ms) */
+    samplingRate?: number;
+    /** Honor Do Not Track browser setting */
+    honorDnt?: boolean;
+    /** API endpoint for sending heatmap data */
+    endpoint?: string;
+    /** Batch size before sending data (default: 50) */
+    batchSize?: number;
+    /** Maximum data points to store locally (default: 1000) */
+    maxDataPoints?: number;
+    /** Session timeout in minutes (default: 30) */
+    sessionTimeout?: number;
+    /** Enable local storage for offline data */
+    persistData?: boolean;
+    /** Storage key prefix (default: 'stx_heatmap') */
+    storagePrefix?: string;
+    /** Custom data attributes to capture on clicks */
+    captureAttributes?: string[];
+    /** Element selectors to ignore */
+    ignoreSelectors?: string[];
+    /** Zone definitions for grouped tracking */
+    zones?: HeatmapZone[];
+    /** Enable visual overlay for development */
+    debugOverlay?: boolean;
+    /** Minimum viewport width to track (mobile optimization) */
+    minViewportWidth?: number;
+    /** Maximum viewport width to track */
+    maxViewportWidth?: number;
 }
 /**
  * Zone definition for grouped tracking
  */
-export declare interface HeatmapZone {
-  id: string
-  selector: string
-  label?: string
+export interface HeatmapZone {
+    /** Zone identifier */
+    id: string;
+    /** CSS selector for the zone */
+    selector: string;
+    /** Zone label for reports */
+    label?: string;
 }
 /**
  * Heatmap data point
  */
-export declare interface HeatmapDataPoint {
-  x: number
-  y: number
-  type: 'move' | 'click' | 'scroll'
-  t: number
-  el?: string
-  zone?: string
-  depth?: number
-  attrs?: Record<string, string>
+export interface HeatmapDataPoint {
+    /** X coordinate (percentage of viewport) */
+    x: number;
+    /** Y coordinate (percentage of viewport) */
+    y: number;
+    /** Type of interaction */
+    type: 'move' | 'click' | 'scroll';
+    /** Timestamp */
+    t: number;
+    /** Element selector (for clicks) */
+    el?: string;
+    /** Zone ID if within a defined zone */
+    zone?: string;
+    /** Scroll depth percentage (for scroll events) */
+    depth?: number;
+    /** Custom attributes captured */
+    attrs?: Record<string, string>;
 }
 /**
  * Heatmap session data
  */
-export declare interface HeatmapSession {
-  sid: string
-  page: string
-  vw: number
-  vh: number
-  points: HeatmapDataPoint[]
-  started: number
-  lastActivity: number
+export interface HeatmapSession {
+    /** Anonymous session ID */
+    sid: string;
+    /** Page URL (path only, no query params for privacy) */
+    page: string;
+    /** Viewport width */
+    vw: number;
+    /** Viewport height */
+    vh: number;
+    /** Data points */
+    points: HeatmapDataPoint[];
+    /** Session start time */
+    started: number;
+    /** Last activity time */
+    lastActivity: number;
 }
+/**
+ * Default heatmap configuration
+ */
+export declare const defaultHeatmapConfig: HeatmapConfig;
+/**
+ * Generate heatmap tracking script based on configuration
+ */
+export declare function generateHeatmapScript(options: StxOptions): string;
+/**
+ * Inject heatmap script into HTML
+ * Scripts are injected just before </body> for optimal loading
+ */
+export declare function injectHeatmap(html: string, options: StxOptions): string;
+/**
+ * Custom @heatmap directive for explicit placement
+ */
+export declare const heatmapDirective: CustomDirective;
 /**
  * Server-side heatmap data aggregator
  * For processing collected heatmap data into visualizations
  */
 export declare class HeatmapAggregator {
-  addSession(data: HeatmapSession): void;
-  getPageData(page: string): HeatmapDataPoint[];
-  getClickData(page: string): HeatmapDataPoint[];
-  getMovementData(page: string): HeatmapDataPoint[];
-  getScrollData(page: string): { depth: number, count: number }[];
-  getZoneStats(page: string): Map<string, { clicks: number, hovers: number }>;
-  generateGridData(page: string, gridSize?: number): { x: number, y: number, intensity: number }[][];
-  exportJSON(): string;
-  clear(): void;
-  get sessionCount(): number;
-  get totalPoints(): number;
+    private sessions;
+    /**
+     * Add session data
+     */
+    addSession(data: HeatmapSession): void;
+    /**
+     * Get aggregated data for a page
+     */
+    getPageData(page: string): HeatmapDataPoint[];
+    /**
+     * Get click heatmap data
+     */
+    getClickData(page: string): HeatmapDataPoint[];
+    /**
+     * Get movement heatmap data
+     */
+    getMovementData(page: string): HeatmapDataPoint[];
+    /**
+     * Get scroll depth data
+     */
+    getScrollData(page: string): {
+        depth: number;
+        count: number;
+    }[];
+    /**
+     * Get zone interaction statistics
+     */
+    getZoneStats(page: string): Map<string, {
+        clicks: number;
+        hovers: number;
+    }>;
+    /**
+     * Generate heatmap grid data (for server-side rendering)
+     */
+    generateGridData(page: string, gridSize?: number): {
+        x: number;
+        y: number;
+        intensity: number;
+    }[][];
+    /**
+     * Export all data as JSON
+     */
+    exportJSON(): string;
+    /**
+     * Clear all data
+     */
+    clear(): void;
+    /**
+     * Get session count
+     */
+    get sessionCount(): number;
+    /**
+     * Get total data points
+     */
+    get totalPoints(): number;
 }
+/**
+ * Create a heatmap aggregator instance
+ */
+export declare function createHeatmapAggregator(): HeatmapAggregator;

package/dist/html-masking.d.ts

@@ -1,3 +1,35 @@
+/**
+ * Element-position-aware masking.
+ *
+ * Several pipeline stages temporarily replace `<script>…</script>` bodies or
+ * `<!-- … -->` comments with sentinel placeholders so later passes don't process
+ * their contents, then restore them at the end. A naive global regex
+ * (`/<script…>…<\/script>/g`, `/<!--…-->/g`) also matches such a token when it
+ * appears INSIDE a quoted attribute value — e.g. `aria-label="<script>x</script>"`
+ * or `title="<!-- "><img onerror=alert(1)> -->"`. The renderer's HTML-escaping
+ * then runs against the harmless placeholder, and the raw token is restored into
+ * the attribute afterward, breaking out of it — an XSS.
+ *
+ * `maskAtElementPosition` walks the string tracking tag/attribute/quote state and
+ * only masks tokens that begin at *element position* (not within an open tag, not
+ * inside a quoted attribute value). A token embedded in an attribute is left in
+ * place to be escaped normally.
+ *
+ * This is a leaf module (no stx imports) so any stage can use it without risking
+ * an import cycle.
+ *
+ * @module html-masking
+ */
+/**
+ * Locate a maskable token starting at `html[i]`.
+ * @returns the end index (exclusive) of the token, or -1 if none starts here.
+ */
+export type TokenMatcher = (html: string, i: number) => number;
+export interface ElementPositionToken {
+    start: number;
+    end: number;
+    token: string;
+}
 /** Matches a real `<script…>…</script>` element (through the first `</script>`). */
 export declare function matchScriptElement(html: string, i: number): number;
 /** Matches a real `<style…>…</style>` element (through the first `</style>`). */
@@ -19,45 +51,19 @@ export declare function scanAtElementPosition(html: string, match: TokenMatcher)
  * Note: HTML attributes do not use backslash escaping, so a `"`/`'` always
  * toggles the surrounding quote — matching how browsers parse attribute values.
  */
-export declare function maskAtElementPosition(html: string, match: TokenMatcher, placeholder: (token: string, index: number) => string): { output: string, tokens: string[] };
+export declare function maskAtElementPosition(html: string, match: TokenMatcher, placeholder: (token: string, index: number) => string): {
+    output: string;
+    tokens: string[];
+};
 /**
  * Stash genuine `<script>…</script>` ELEMENTS behind NUL-byte sentinels so a
  * component scanner doesn't mis-resolve tag-like JS string literals (e.g.
  * `div.innerHTML = '<v:shape>'`) as component references (stacksjs/stx#1730), and
  * so an attribute-embedded `<script>` is never pulled out and restored unescaped.
  */
-export declare function stashScriptElements(html: string): { output: string, scripts: string[] };
+export declare function stashScriptElements(html: string): {
+    output: string;
+    scripts: string[];
+};
 /** Restore scripts stashed by {@link stashScriptElements}. */
 export declare function restoreStashedScripts(html: string, scripts: string[]): string;
-export declare interface ElementPositionToken {
-  start: number
-  end: number
-  token: string
-}
-/**
- * Element-position-aware masking.
- *
- * Several pipeline stages temporarily replace `<script>…</script>` bodies or
- * `<!-- … -->` comments with sentinel placeholders so later passes don't process
- * their contents, then restore them at the end. A naive global regex
- * (`/<script…>…<\/script>/g`, `/<!--…-->/g`) also matches such a token when it
- * appears INSIDE a quoted attribute value — e.g. `aria-label="<script>x</script>"`
- * or `title="<!-- "><img onerror=alert(1)> -->"`. The renderer's HTML-escaping
- * then runs against the harmless placeholder, and the raw token is restored into
- * the attribute afterward, breaking out of it — an XSS.
- *
- * `maskAtElementPosition` walks the string tracking tag/attribute/quote state and
- * only masks tokens that begin at *element position* (not within an open tag, not
- * inside a quoted attribute value). A token embedded in an attribute is left in
- * place to be escaped normally.
- *
- * This is a leaf module (no stx imports) so any stage can use it without risking
- * an import cycle.
- *
- * @module html-masking
- */
-/**
- * Locate a maskable token starting at `html[i]`.
- * @returns the end index (exclusive) of the token, or -1 if none starts here.
- */
-export type TokenMatcher = (html: string, i: number) => number;

package/dist/hydration-runtime.d.ts

@@ -1,3 +1,23 @@
+/**
+ * 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
+ */
+export interface IslandMeta {
+    id: string;
+    component: string;
+    strategy: string;
+    props: Record<string, unknown>;
+}
 /**
  * Generate the unified hydration bootstrap script.
  *
@@ -22,27 +42,3 @@ export declare function extractComponentName(content: string): string | null;
  * Parses :prop="value" bindings.
  */
 export declare function extractBoundProps(content: string, context: Record<string, unknown>): Record<string, unknown>;
-/* eslint-disable prefer-const, style/max-statements-per-line, no-super-linear-backtracking, regexp/no-unused-capturing-group */
-/**
- * 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/i18n.d.ts

@@ -1,4 +1,89 @@
+/**
+ * Module for internationalization (i18n) support
+ *
+ * Features:
+ * - Translation file loading (JSON, YAML, JS)
+ * - Lazy loading with deduplication
+ * - Background preloading for multiple locales
+ * - Nested key access (e.g., 'messages.welcome')
+ * - Parameter replacement (e.g., ':name' → 'John')
+ * - Basic pluralization support
+ * - ICU MessageFormat support
+ * - Translation caching with invalidation
+ *
+ * ## Lazy Loading
+ *
+ * Translations are loaded lazily with request deduplication:
+ * ```ts
+ * // Multiple simultaneous calls share the same promise
+ * const [t1, t2] = await Promise.all([
+ *   loadTranslation('en', options),
+ *   loadTranslation('en', options), // Reuses same request
+ * ])
+ * ```
+ *
+ * ## Background Preloading
+ *
+ * Preload translations in the background:
+ * ```ts
+ * // Fire and forget - doesn't block
+ * preloadTranslationsBackground({
+ *   locales: ['en', 'es', 'fr', 'de'],
+ *   parallel: true,
+ *   onLocaleLoaded: (locale) => console.log(`${locale} ready`)
+ * }, options)
+ *
+ * // Later, check if loaded or wait
+ * if (isLoaded('es')) {
+ *   const translations = getTranslationSync('es')
+ * }
+else {
+ *   await waitForLocale('es', 5000) // Wait up to 5s
+ * }
+ * ```
+ *
+ * ## Pluralization
+ *
+ * Use the `|` separator to define plural forms:
+ * ```yaml
+ * items: "One item|:count items"
+ * ```
+ *
+ * Or for more complex pluralization:
+ * ```yaml
+ * apples: "{0} No apples|{1} One apple|[2,*] :count apples"
+ * ```
+ *
+ * ## Cache Management
+ *
+ * The translation cache can be managed via:
+ * - `clearTranslationCache()` - Clear all cached translations
+ * - `clearTranslationCache('en')` - Clear specific locale
+ * - `getTranslationCacheStats()` - Get cache statistics
+ */
 import type { I18nConfig, StxOptions } from './types';
+export declare const defaultI18nConfig: I18nConfig;
+/**
+ * Loading state for async translation loading
+ */
+type LoadingState = 'idle' | 'loading' | 'loaded' | 'error';
+/**
+ * Preload configuration
+ */
+export interface PreloadConfig {
+    /** Locales to preload */
+    locales: string[];
+    /** Whether to load in parallel (true) or sequentially (false) */
+    parallel?: boolean;
+    /** Priority order - higher priority locales load first in sequential mode */
+    priority?: Record<string, number>;
+    /** Callback when a locale finishes loading */
+    onLocaleLoaded?: (locale: string) => void;
+    /** Callback when all locales are loaded */
+    onComplete?: () => void;
+    /** Callback on error */
+    onError?: (locale: string, error: Error) => void;
+}
 /**
  * Clear the translation cache
  * @param locale - Optional locale to clear. If not provided, clears all.
@@ -8,9 +93,13 @@ 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 }>
+    size: number;
+    locales: string[];
+    entries: Array<{
+        locale: string;
+        loadedAt: Date;
+        keyCount: number;
+    }>;
 };
 /**
  * Get the loading state for a locale
@@ -221,37 +310,9 @@ export declare function getTranslation(key: string, translations: Record<string,
 /**
  * Process @translate directive
  */
-// eslint-disable-next-line pickier/no-unused-vars
 export declare function processTranslateDirective(template: string, context: Record<string, any>, filePath: string, options: StxOptions): Promise<string>;
 /**
  * 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;
-/**
- * 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
-}
-/**
- * Signature of ts-i18n's `loadLocale`. Returns the merged translation tree for
- * a locale, or `undefined` when no file exists for it.
- */
-declare type LoadLocaleFn = (
-  locale: string,
-  options: { translationsDir: string, defaultLocale?: string, sources?: Array<'ts' | 'yaml' | 'json'> },
-) => Promise<Record<string, any> | undefined>;
-/**
- * Loading state for async translation loading
- */
-declare type LoadingState = 'idle' | 'loading' | 'loaded' | 'error';
+export {};

package/dist/image-optimization/auto-sibling.d.ts

@@ -1,3 +1,35 @@
+/**
+ * Auto-Sibling Image Discovery
+ *
+ * NuxtImage-style sugar: if a `.webp` (or `.avif`) sits next to a `.jpg`/
+ * `.png` on disk, rewrite plain `<img src="hero.jpg">` into
+ *
+ *   <picture>
+ *     <source type="image/avif" srcset="/images/hero.avif">
+ *     <source type="image/webp" srcset="/images/hero.webp">
+ *     <img src="/images/hero.jpg" alt="…">
+ *   </picture>
+ *
+ * No consumer change required — drop the optimized format next to the
+ * original asset and capable browsers pick it up.
+ *
+ * Skipped intentionally:
+ *   - `<img>` already inside a `<picture>` (don't double-wrap)
+ *   - Remote URLs (http://, https://, protocol-relative `//cdn/…`)
+ *   - data: URIs
+ *   - sources whose extension isn't a known raster format
+ *   - images whose resolved path is outside `publicDir` (we don't probe
+ *     arbitrary paths on disk)
+ */
+export interface AutoSiblingOptions {
+    /** Filesystem root for resolving src URLs (typically the stx config's `publicDir`). */
+    publicDir: string;
+    /** Sibling formats to probe for, in priority order (most-preferred first). */
+    formats?: Array<{
+        ext: string;
+        mime: string;
+    }>;
+}
 /**
  * Scan `html` for plain `<img>` tags whose src resolves to a real file
  * inside `publicDir`, probe for sibling-format files (e.g. `hero.webp`
@@ -8,7 +40,3 @@
  * found, returns the input unchanged (no allocations beyond the scan).
  */
 export declare function rewriteImagesWithSiblings(html: string, options: AutoSiblingOptions): Promise<string>;
-export declare interface AutoSiblingOptions {
-  publicDir: string
-  formats?: Array<{ ext: string, mime: string }>
-}

package/dist/includes.d.ts

@@ -1,5 +1,73 @@
-import { LRUCache } from './performance-utils';
+/**
+ * Includes Module
+ *
+ * Processes include, partial, and stack directives for template composition.
+ * This module enables building complex templates from reusable pieces.
+ *
+ * ## Include Directives
+ *
+ * | Directive | Description |
+ * |-----------|-------------|
+ * | `@include('path')` | Include a partial template |
+ * | `@include('path', { vars })` | Include with local variables |
+ * | `@partial('path')` | Alias for @include |
+ * | `@includeIf('path')` | Include only if file exists |
+ * | `@includeWhen(cond, 'path')` | Include if condition is true |
+ * | `@includeUnless(cond, 'path')` | Include if condition is false |
+ * | `@includeFirst(['a','b'])` | Include first existing file |
+ * | `@once...@endonce` | Include content only once per request |
+ *
+ * ## Stack Directives
+ *
+ * | Directive | Description |
+ * |-----------|-------------|
+ * | `@push('name')...@endpush` | Add content to end of stack |
+ * | `@prepend('name')...@endprepend` | Add content to start of stack |
+ * | `@stack('name')` | Output stack contents |
+ *
+ * ## Path Resolution
+ *
+ * Paths are resolved in this order:
+ * 1. If path starts with `./` or `../`: Relative to current template
+ * 2. Otherwise: Relative to `partialsDir` (from config)
+ *
+ * Paths without `.stx` extension automatically get it appended.
+ *
+ * ## Security
+ *
+ * Path traversal attacks are blocked. Includes must resolve to:
+ * - The configured partials directory, OR
+ * - The directory containing the current template
+ *
+ * Uses safe evaluation for expression evaluation to prevent code injection.
+ *
+ * ## @once Directive
+ *
+ * The `@once` directive ensures content is only rendered once per request.
+ * This is useful for including scripts or styles that should not be duplicated.
+ *
+ * **Important**: In server environments, use request-scoped tracking:
+ *
+ * ```typescript
+ * // Option 1: Clear global store per request
+ * app.use((req, res, next) => {
+ *   clearOnceStore()
+ *   next()
+ * })
+ *
+ * // Option 2: Use request-scoped store (recommended)
+ * const context = {
+ *   __onceStore: new Set<string>(),
+ *   ...otherData
+ * }
+ * ```
+ *
+ * @module includes
+ */
 import type { StxOptions } from './types';
+import { LRUCache } from './performance-utils';
+export declare const partialsCache: LRUCache<string, string>;
+export declare const onceStore: Set<string>;
 /**
  * Clear the @once store - useful for testing and resetting state
  *
@@ -101,9 +169,3 @@ export declare function processStackPushDirectives(template: string, stacks: Rec
  * ```
  */
 export declare function processStackReplacements(template: string, stacks: Record<string, 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>;