@stacksjs/stx 0.2.0 → 0.2.3

package/dist/media/upload/component.d.ts

@@ -0,0 +1,23 @@
+import type { MediaUploadProps,  } from '../types';
+/**
+ * Render a file upload component
+ *
+ * @example
+ * ```typescript
+ * const html = renderMediaUpload({
+ *   endpoint: '/api/upload',
+ *   accept: 'image/*',
+ *   maxSize: 10 * 1024 * 1024, // 10MB
+ *   preview: true,
+ *   dropzone: true,
+ * })
+ * ```
+ */
+/*',
+ *   maxSize: 10 * 1024 * 1024, // 10MB
+ *   preview: true,
+ *   dropzone: true,
+ * })
+ * ```
+ */
+export declare function renderMediaUpload(props: MediaUploadProps): { html: string; script: string; css: string };

package/dist/media/upload/index.d.ts

@@ -0,0 +1 @@
+export { renderMediaUpload } from './component';

package/dist/media/video/directive.d.ts

@@ -0,0 +1,9 @@
+import type { CustomDirective } from '../../types';
+/**
+ * Create the @video directive
+ */
+export declare function createVideoDirective(): CustomDirective;
+/**
+ * The @video directive instance
+ */
+export declare const videoDirective: unknown;

package/dist/media/video/index.d.ts

@@ -0,0 +1,47 @@
+import type { VideoProps, VideoRenderResult, EnhancedVideoProps, TsVideosConfig, ProcessedVideoResult,  } from '../types';
+/**
+ * Render a video component
+ *
+ * Supports both standard VideoProps and EnhancedVideoProps with ts-videos integration.
+ *
+ * @example
+ * ```typescript
+ * // Native HTML5 video
+ * const result = await renderVideoComponent({
+ *   src: '/videos/intro.mp4',
+ *   poster: '/images/poster.jpg',
+ *   controls: true,
+ *   lazy: true,
+ * })
+ *
+ * // With ts-video-player for advanced features
+ * const result = await renderVideoComponent({
+ *   src: 'https://youtube.com/watch?v=xxx',
+ *   player: 'ts-video',
+ *   lazy: true,
+ * })
+ *
+ * // With ts-videos processing
+ * const result = await renderVideoComponent({
+ *   src: '/videos/raw.mov',
+ *   process: true,
+ *   quality: 'high',
+ *   generatePoster: { timestamp: 5 },
+ *   streaming: { format: 'hls' },
+ * }, { tsVideosConfig: { enabled: true, outputDir: 'dist/videos' } })
+ * ```
+ */
+export declare function renderVideoComponent(props: VideoProps | EnhancedVideoProps, context?: { isDev?: boolean } | ExtendedVideoRenderContext): Promise<VideoRenderResult>;
+/**
+ * Parse @video directive options (legacy - use videoDirective instead)
+ */
+export declare function parseVideoDirectiveOptions(content: string, params: Record<string, unknown>, context: Record<string, unknown>): VideoProps;
+/**
+ * Extended video render context with ts-videos config
+ */
+export declare interface ExtendedVideoRenderContext {
+  isDev?: boolean
+  tsVideosConfig?: TsVideosConfig
+  processedResult?: ProcessedVideoResult
+}
+export { createVideoDirective, videoDirective } from './directive';

package/dist/media/video/processor/cache.d.ts

@@ -0,0 +1,33 @@
+import {  } from '../../shared/cache';
+import type { EnhancedVideoProps, ProcessedVideoResult, TsVideosConfig,  } from '../../types';
+/**
+ * Get cached video processing result
+ */
+export declare function getCachedVideoResult(src: string, options: Partial<EnhancedVideoProps>, config?: TsVideosConfig): Promise<ProcessedVideoResult | null>;
+/**
+ * Set cached video processing result
+ */
+export declare function setCachedVideoResult(src: string, options: Partial<EnhancedVideoProps>, result: ProcessedVideoResult, config?: TsVideosConfig): Promise<void>;
+/**
+ * Clear video processing cache
+ */
+export declare function clearVideoCache(): Promise<void>;
+/**
+ * Video processor cache configuration
+ */
+export declare interface VideoCacheConfig extends CacheConfig {
+  cacheTranscoded?: boolean
+  cacheThumbnails?: boolean
+  cacheManifests?: boolean
+}
+/**
+ * Video processor cache class
+ */
+export declare class VideoProcessorCache {
+  private config: VideoCacheConfig;
+  constructor(config?: Partial<VideoCacheConfig>);
+  get(src: string, options: Partial<EnhancedVideoProps>): Promise<ProcessedVideoResult | null>;
+  set(src: string, options: Partial<EnhancedVideoProps>, result: ProcessedVideoResult): Promise<void>;
+  clear(): Promise<void>;
+  updateConfig(config: Partial<VideoCacheConfig>): void;
+}

package/dist/media/video/processor/index.d.ts

@@ -0,0 +1,21 @@
+export type {
+  EnhancedVideoProps,
+  ProcessedVideoResult,
+  TsVideosConfig,
+  VideoQualityPreset,
+  VideoPlatformPreset,
+  TranscodeConfig,
+  TranscodeResult,
+  ThumbnailResult,
+  HLSResult,
+  DASHResult,
+  StreamingConfig,
+  StreamingQualityLevel,
+  PosterGenerationConfig,
+  SpriteSheetConfig,
+  WaveformConfig,
+} from '../../types';
+export { processVideo, analyzeVideo } from './transcoder';
+export { generatePoster, generateThumbnails, generateSpriteSheet } from './thumbnail';
+export { generateHLSManifest, generateDASHManifest } from './streaming';
+export { getCachedVideoResult, setCachedVideoResult, clearVideoCache, VideoProcessorCache } from './cache';

package/dist/media/video/processor/streaming.d.ts

@@ -0,0 +1,19 @@
+import type { HLSResult, DASHResult, StreamingQualityLevel,  } from '../../types';
+/**
+ * Generate HLS (HTTP Live Streaming) manifest and segments
+ */
+export declare function generateHLSManifest(src: string, qualities: StreamingQualityLevel[], outputDir: string, baseUrl: string, options?: {
+    segmentDuration?: number
+    playlistType?: 'vod' | 'event'
+  }): Promise<HLSResult | null>;
+/**
+ * Generate DASH (Dynamic Adaptive Streaming over HTTP) manifest
+ */
+export declare function generateDASHManifest(src: string, qualities: StreamingQualityLevel[], outputDir: string, baseUrl: string, options?: {
+    segmentDuration?: number
+    minBufferTime?: number
+  }): Promise<DASHResult | null>;
+/**
+ * Default streaming quality levels
+ */
+export declare const DEFAULT_STREAMING_QUALITIES: StreamingQualityLevel[];

package/dist/media/video/processor/thumbnail.d.ts

@@ -0,0 +1,28 @@
+import type { ThumbnailResult, PosterGenerationConfig, SpriteSheetConfig,  } from '../../types';
+/**
+ * Generate poster/thumbnail from video at specific timestamp
+ */
+export declare function generatePoster(src: string, options: PosterGenerationConfig, outputDir: string, baseUrl: string): Promise<ThumbnailResult | null>;
+/**
+ * Generate multiple thumbnails at intervals
+ */
+export declare function generateThumbnails(src: string, options: {
+    count?: number
+    interval?: number
+    format?: 'jpeg' | 'png' | 'webp'
+    width?: number
+    quality?: number
+  }, outputDir: string, baseUrl: string): Promise<ThumbnailResult[]>;
+/**
+ * Generate sprite sheet for video scrubbing preview
+ */
+export declare function generateSpriteSheet(src: string, options: SpriteSheetConfig, outputDir: string, baseUrl: string): Promise<{
+  url: string
+  path: string
+  columns: number
+  rows: number
+  thumbnailWidth: number
+  thumbnailHeight: number
+  interval: number
+  totalFrames: number
+} | null>;

package/dist/media/video/processor/transcoder.d.ts

@@ -0,0 +1,9 @@
+import type { EnhancedVideoProps, ProcessedVideoResult, TsVideosConfig,  } from '../../types';
+/**
+ * Analyze video to get metadata
+ */
+export declare function analyzeVideo(src: string): Promise<ProcessedVideoResult['metadata'] | null>;
+/**
+ * Process a video with ts-videos
+ */
+export declare function processVideo(src: string, options: Partial<EnhancedVideoProps>, config: TsVideosConfig, onProgress?: (progress: { percentage: number; stage: string }) => void): Promise<ProcessedVideoResult>;

package/dist/middleware.d.ts

@@ -1,13 +1,52 @@
 import type { StxOptions } from './types';
 /**
- * Process middleware registered in the application
+ * Process middleware registered in the application.
+ *
+ * Executes all middleware handlers that match the specified timing in sequence.
+ * Each middleware receives the current template and can modify it.
+ *
+ * @param template - The template string to process
+ * @param context - Template context with variables (can be modified by middleware)
+ * @param filePath - Path to the template file (for error messages)
+ * @param options - STX processing options containing middleware configuration
+ * @param timing - When to run: 'before' or 'after' directive processing
+ * @returns The processed template string
+ *
+ * @example
+ * ```typescript
+ * const processed = await processMiddleware(
+ *   '<div>{{ content }}</div>',
+ *   { content: 'Hello' },
+ *   '/path/to/template.stx',
+ *   { middleware: myMiddleware },
+ *   'before'
+ * )
+ * ```
  */
 export declare function processMiddleware(template: string, context: Record<string, any>, filePath: string, options: StxOptions, timing: 'before' | 'after'): Promise<string>;
 /**
- * Run pre-processing middleware
+ * Run pre-processing middleware (timing: 'before').
+ *
+ * This is a convenience wrapper for `processMiddleware` with timing='before'.
+ * Pre-processing middleware runs before any directives are processed.
+ *
+ * @param template - The raw template string
+ * @param context - Template context with variables
+ * @param filePath - Path to the template file
+ * @param options - STX processing options
+ * @returns The pre-processed template string
  */
 export declare function runPreProcessingMiddleware(template: string, context: Record<string, any>, filePath: string, options: StxOptions): Promise<string>;
 /**
- * Run post-processing middleware
+ * Run post-processing middleware (timing: 'after').
+ *
+ * This is a convenience wrapper for `processMiddleware` with timing='after'.
+ * Post-processing middleware runs after all directives have been processed.
+ *
+ * @param template - The processed template string
+ * @param context - Template context with variables
+ * @param filePath - Path to the template file
+ * @param options - STX processing options
+ * @returns The post-processed template string
  */
 export declare function runPostProcessingMiddleware(template: string, context: Record<string, any>, filePath: string, options: StxOptions): Promise<string>;

package/dist/native-build.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Build an stx template into a native application
+ */
+export declare function buildNative(config: NativeBuildConfig): Promise<NativeBuildResult>;
+/**
+ * Get available targets for current platform
+ */
+export declare function getAvailableTargets(): NativeTarget[];
+/**
+ * Get available formats for a target
+ */
+export declare function getAvailableFormats(target: NativeTarget): NativeFormat[];
+export declare interface NativeBuildConfig {
+  input: string
+  output?: string
+  target?: NativeTarget
+  format?: NativeFormat
+  name?: string
+  version?: string
+  description?: string
+  author?: string
+  bundleId?: string
+  icon?: string
+  window?: {
+    title?: string
+    width?: number
+    height?: number
+    resizable?: boolean
+    frameless?: boolean
+    transparent?: boolean
+    alwaysOnTop?: boolean
+    fullscreen?: boolean
+  }
+  sidebar?: {
+    /** Enable native macOS sidebar */
+    enabled?: boolean
+    /** Sidebar width in pixels */
+    width?: number
+    /** Sidebar sections and items */
+    config?: {
+      sections: Array<{
+        id: string
+        title: string
+        items: Array<{
+          id: string
+          label: string
+          icon?: string
+          badge?: string | number
+          tintColor?: string
+        }>
+      }>
+      minWidth?: number
+      maxWidth?: number
+      canCollapse?: boolean
+    }
+  }
+  systemTray?: boolean
+  hotReload?: boolean
+  devTools?: boolean
+  craftPath?: string
+  env?: Record<string, string>
+  verbose?: boolean
+}
+export declare interface NativeBuildResult {
+  success: boolean
+  target: NativeTarget
+  format: NativeFormat
+  outputPath?: string
+  error?: string
+  duration?: number
+}
+export type NativeTarget = 'macos' | 'windows' | 'linux' | 'ios' | 'android'
+export type NativeFormat = 'app' | 'dmg' | 'pkg' | 'msi' | 'zip' | 'deb' | 'rpm' | 'appimage' | 'ipa' | 'apk'
+export default nativeBuild;

package/dist/parser/directive-parser.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Extract a parenthesized expression from a string, handling nested parens
+ * e.g., "func(a, fn(b, c))" -> { expression: "func(a, fn(b, c))", endPos: 17 }
+ */
+export declare function extractParenthesizedExpression(source: string, startPos: number): {
+  expression: string
+  endPos: number
+} | null;
+/**
+ * Find the matching end tag for a directive, handling nested instances
+ *
+ * @param source - The source string to search in
+ * @param startName - The opening directive name (e.g., "if", "foreach")
+ * @param endName - The closing directive name (e.g., "endif", "endforeach")
+ * @param startPos - Position to start searching from (after the opening directive)
+ * @returns The position of the matching end tag, or -1 if not found
+ */
+export declare function findMatchingEndTag(source: string, startName: string, endName: string, startPos: number): number;
+/**
+ * Parse a complete conditional block (@if, @elseif, @else, @endif)
+ *
+ * @param source - The source string
+ * @param startPos - Position where @if starts
+ * @returns Parsed conditional with all branches, or null if malformed
+ */
+export declare function parseConditionalBlock(source: string, startPos: number): ParsedConditional | null;
+/**
+ * Find all @if blocks in source (non-nested, outermost only)
+ */
+export declare function findIfBlocks(source: string): ParsedConditional[];
+/**
+ * Find a directive with its content
+ *
+ * @param source - Source string
+ * @param directiveName - Name without @ (e.g., "foreach")
+ * @param endDirectiveName - End name without @ (e.g., "endforeach")
+ * @returns All matches found
+ */
+export declare function findDirectiveBlocks(source: string, directiveName: string, endDirectiveName: string): DirectiveMatch[];
+export declare function parseSwitchBlock(source: string, startPos: number): ParsedSwitch | null;
+// =============================================================================
+// Types
+// =============================================================================
+export declare interface DirectiveMatch {
+  fullMatch: string
+  name: string
+  params: string
+  content: string
+  start: number
+  end: number
+}
+export declare interface ConditionalBranch {
+  type: 'if' | 'elseif' | 'else'
+  condition?: string
+  content: string
+  start: number
+  end: number
+}
+export declare interface ParsedConditional {
+  fullMatch: string
+  branches: ConditionalBranch[]
+  start: number
+  end: number
+}
+/**
+ * Parse @switch block with proper handling of nested switches
+ */
+export declare interface SwitchCase {
+  type: 'case' | 'default'
+  value?: string
+  content: string
+}
+export declare interface ParsedSwitch {
+  fullMatch: string
+  expression: string
+  cases: SwitchCase[]
+  start: number
+  end: number
+}

package/dist/parser/expression-parser.d.ts

@@ -0,0 +1,59 @@
+import { extractBalancedExpression, findMatchingDelimiter, splitByPipe, Tokenizer } from './tokenizer';
+/**
+ * Find all template expressions in source ({{ }} and {!! !!})
+ */
+export declare function findExpressions(source: string): ExpressionMatch[];
+/**
+ * Parse an expression with optional filter chain
+ * e.g., "value | uppercase | truncate(10)" -> { baseExpression: "value", filters: [...] }
+ */
+export declare function parseExpressionWithFilters(expression: string): ParsedExpression;
+/**
+ * Parse comma-separated arguments, respecting nesting
+ */
+export declare function parseArguments(argsString: string): string[];
+/**
+ * Extract directive parameters from parentheses
+ * e.g., "@foreach($items as $item)" -> "$items as $item"
+ */
+export declare function extractDirectiveParams(source: string, directiveEnd: number): {
+  params: string
+  endPos: number
+} | null;
+/**
+ * Parse script content and extract declarations
+ */
+export declare function parseScriptDeclarations(scriptContent: string): ScriptDeclaration[];
+// =============================================================================
+// Expression Extraction
+// =============================================================================
+export declare interface ExpressionMatch {
+  fullMatch: string
+  expression: string
+  start: number
+  end: number
+  isRaw: boolean
+}
+// =============================================================================
+// Filter Parsing
+// =============================================================================
+export declare interface FilterCall {
+  name: string
+  args: string[]
+}
+export declare interface ParsedExpression {
+  baseExpression: string
+  filters: FilterCall[]
+}
+// =============================================================================
+// Script Parsing Utilities
+// =============================================================================
+export declare interface ScriptDeclaration {
+  type: 'variable' | 'function'
+  name: string
+  value: string
+  exported: boolean
+  start: number
+  end: number
+}
+export { extractBalancedExpression, findMatchingDelimiter, splitByPipe, Tokenizer };

package/dist/parser/index.d.ts

@@ -0,0 +1,35 @@
+export {
+  type ConditionalBranch,
+  type DirectiveMatch,
+  extractParenthesizedExpression,
+  findDirectiveBlocks,
+  findIfBlocks,
+  findMatchingEndTag,
+  parseConditionalBlock,
+  type ParsedConditional,
+  type ParsedSwitch,
+  parseSwitchBlock,
+  type SwitchCase,
+} from './directive-parser';
+export {
+  type ExpressionMatch,
+  extractDirectiveParams,
+  type FilterCall,
+  findExpressions,
+  parseArguments,
+  type ParsedExpression,
+  parseExpressionWithFilters,
+  parseScriptDeclarations,
+  type ScriptDeclaration,
+} from './expression-parser';
+export {
+  type Token,
+  Tokenizer,
+  type TokenizerState,
+  type TokenType,
+} from './tokenizer';
+export {
+  extractBalancedExpression,
+  findMatchingDelimiter,
+  splitByPipe,
+} from './tokenizer';

package/dist/parser/tokenizer.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Find matching closing delimiter, respecting nesting and strings
+ */
+export declare function findMatchingDelimiter(source: string, openChar: string, closeChar: string, startPos?: number): number;
+/**
+ * Extract a balanced expression from source starting at position
+ */
+export declare function extractBalancedExpression(source: string, startPos: number): {
+  expression: string
+  endPos: number
+};
+/**
+ * Split expression by pipe (|) for filters, respecting nesting
+ */
+export declare function splitByPipe(expression: string): string[];
+export declare interface Token {
+  type: TokenType
+  value: string
+  start: number
+  end: number
+  line: number
+  column: number
+}
+export declare interface TokenizerState {
+  pos: number
+  line: number
+  column: number
+}
+/**
+ * Tokenizer for Template Expressions
+ *
+ * A character-by-character tokenizer that properly handles:
+ * - Nested braces, brackets, and parentheses
+ * - String literals (single, double, and template)
+ * - Escaped characters within strings
+ * - Template literal expressions `${...}`
+ *
+ * @module parser/tokenizer
+ */
+// =============================================================================
+// Token Types
+// =============================================================================
+export type TokenType = | 'STRING' // 'string' or "string"
+  | 'TEMPLATE_STRING' // `template ${expr} string`
+  | 'NUMBER'
+  | 'IDENTIFIER'
+  | 'OPERATOR'
+  | 'PUNCTUATION' // ( ) [ ] { } , ; :
+  | 'WHITESPACE'
+  | 'COMMENT'
+  | 'EXPRESSION_START' // {{
+  | 'EXPRESSION_END' // }}
+  | 'RAW_START' // {!!
+  | 'RAW_END' // !!}
+  | 'DIRECTIVE' // @name
+  | 'EOF'
+/**
+ * Tokenizer for template expressions
+ */
+export declare class Tokenizer {
+  private source: string;
+  private pos: number;
+  private line: number;
+  private column: number;
+  private tokens: Token[];
+  constructor(source: string);
+  tokenize(): Token[];
+  private nextToken(): Token | null;
+  private readWhitespace(start: number, startLine: number, startColumn: number): Token;
+  private readLineComment(start: number, startLine: number, startColumn: number): Token;
+  private readBlockComment(start: number, startLine: number, startColumn: number): Token;
+  private readString(quote: string, start: number, startLine: number, startColumn: number): Token;
+  private readTemplateString(start: number, startLine: number, startColumn: number): Token;
+  private readNumber(start: number, startLine: number, startColumn: number): Token;
+  private readIdentifier(start: number, startLine: number, startColumn: number): Token;
+  private readDirective(start: number, startLine: number, startColumn: number): Token;
+  private advance(count?: number): void;
+  private peek(offset: number): string | undefined;
+  saveState(): TokenizerState;
+  restoreState(state: TokenizerState): void;
+}

package/dist/partial-hydration.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Create a registry for managing island components
+ */
+export declare function createIslandRegistry(): IslandRegistry;
+/**
+ * Process all partial hydration directives
+ */
+export declare function processPartialHydrationDirectives(template: string, context?: Record<string, unknown>, _filePath?: string): string;
+/**
+ * Generate CSS for partial hydration
+ */
+export declare function generatePartialHydrationCSS(): string;
+/**
+ * Manually hydrate an island by ID
+ */
+export declare function hydrateIsland(islandId: string): void;
+/**
+ * Hydrate all islands with a specific strategy
+ */
+export declare function hydrateByStrategy(strategy: HydrationStrategy): void;
+/**
+ * Hydrate all pending islands
+ */
+export declare function hydrateAll(): void;
+/**
+ * Check if an island is hydrated
+ */
+export declare function isHydrated(islandId: string): boolean;
+/**
+ * Wait for an island to be hydrated
+ */
+export declare function onHydrated(islandId: string): Promise<void>;
+/**
+ * Mark content as static (never hydrate)
+ */
+export declare function processStaticDirectives(template: string): string;
+/**
+ * Generate island manifest for client
+ */
+export declare function generateIslandManifest(islands: IslandComponent[]): string;
+export declare interface HydrationOptions {
+  strategy: HydrationStrategy
+  priority?: 'high' | 'low'
+  rootMargin?: string
+  threshold?: number | number[]
+  media?: string
+  event?: string
+  timeout?: number
+  placeholder?: string
+  preserveServerHTML?: boolean
+}
+export declare interface IslandComponent {
+  id: string
+  component: string
+  props: Record<string, unknown>
+  options: HydrationOptions
+  serverHTML: string
+  hydrated: boolean
+}
+export declare interface IslandRegistry {
+  islands: Map<string, IslandComponent>
+  register: (island: IslandComponent) => void
+  get: (id: string) => IslandComponent | undefined
+  hydrate: (id: string) => Promise<void>
+  hydrateAll: () => Promise<void>
+}
+// ============================================================================
+// Types
+// ============================================================================
+export type HydrationStrategy = | 'load'
+  | 'idle'
+  | 'visible'
+  | 'media'
+  | 'only'
+  | 'hover'
+  | 'event'
+export default {
+  processPartialHydrationDirectives,
+  processStaticDirectives,
+  generatePartialHydrationCSS,
+  generateIslandManifest,
+  createIslandRegistry,
+  hydrateIsland,
+  hydrateByStrategy,
+  hydrateAll,
+  isHydrated,
+  onHydrated,
+};