@stacksjs/stx 0.2.154 → 0.2.156

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

@@ -1,3 +1,17 @@
+/**
+ * STX Media - Video Directive
+ *
+ * @video directive for declarative video rendering with ts-videos integration.
+ *
+ * @module media/video/directive
+ *
+ * @example
+ * ```html
+ * @video('/videos/intro.mp4', { controls: true, lazy: true })
+ * @video('/videos/movie.mp4', { quality: 'high', generatePoster: true })
+ * @video(dynamicSrc, { streaming: { format: 'hls' } })
+ * ```
+ */
 import type { CustomDirective } from '../../types';
 /**
  * Create the @video directive
@@ -6,4 +20,4 @@ export declare function createVideoDirective(): CustomDirective;
 /**
  * The @video directive instance
  */
-export declare const videoDirective: unknown;
+export declare const videoDirective: CustomDirective;

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

@@ -1,4 +1,36 @@
+/**
+ * STX Media - Video Module
+ *
+ * Video playback with native HTML5 and ts-video-player integration.
+ *
+ * This module provides a <Video> component that integrates with the
+ * ts-video-player library for advanced playback features including:
+ * - HLS/DASH streaming support
+ * - YouTube/Vimeo embeds with custom controls
+ * - Keyboard shortcuts
+ * - Picture-in-Picture
+ * - Full accessibility support
+ *
+ * With ts-videos integration:
+ * - Video transcoding with quality presets
+ * - Automatic poster/thumbnail generation
+ * - HLS/DASH streaming manifest generation
+ * - Sprite sheet generation for scrubbing preview
+ *
+ * @module media/video
+ */
 import type { VideoProps, VideoRenderResult, EnhancedVideoProps, TsVideosConfig, ProcessedVideoResult } from '../types';
+/**
+ * Extended video render context with ts-videos config
+ */
+export interface ExtendedVideoRenderContext {
+    /** Development mode */
+    isDev?: boolean;
+    /** ts-videos configuration */
+    tsVideosConfig?: TsVideosConfig;
+    /** Pre-processed video result */
+    processedResult?: ProcessedVideoResult;
+}
 /**
  * Render a video component
  *
@@ -31,24 +63,14 @@ import type { VideoProps, VideoRenderResult, EnhancedVideoProps, TsVideosConfig,
  * }, { 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)
- */
-// eslint-disable-next-line pickier/no-unused-vars
-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 declare function renderVideoComponent(props: VideoProps | EnhancedVideoProps, context?: {
+    isDev?: boolean;
+} | ExtendedVideoRenderContext): Promise<VideoRenderResult>;
 /**
  * Parse @video directive options
  */
-// =============================================================================
-// Directive Exports
-// =============================================================================
 export { createVideoDirective, videoDirective } from './directive';
+/**
+ * Parse @video directive options (legacy - use videoDirective instead)
+ */
+export declare function parseVideoDirectiveOptions(content: string, params: Record<string, unknown>, context: Record<string, unknown>): VideoProps;

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

@@ -1,5 +1,46 @@
-import { type CacheConfig } from '../../shared/cache';
+/**
+ * STX Media - Video Processing Cache
+ *
+ * Specialized cache for video processing results.
+ *
+ * @module media/video/processor/cache
+ */
 import type { EnhancedVideoProps, ProcessedVideoResult, TsVideosConfig } from '../../types';
+import { type CacheConfig } from '../../shared/cache';
+/**
+ * Video processor cache configuration
+ */
+export interface VideoCacheConfig extends CacheConfig {
+    /** Cache transcoded videos */
+    cacheTranscoded?: boolean;
+    /** Cache thumbnails separately */
+    cacheThumbnails?: boolean;
+    /** Cache streaming manifests */
+    cacheManifests?: boolean;
+}
+/**
+ * Video processor cache class
+ */
+export declare class VideoProcessorCache {
+    private config;
+    constructor(config?: Partial<VideoCacheConfig>);
+    /**
+     * Get cached processing result
+     */
+    get(src: string, options: Partial<EnhancedVideoProps>): Promise<ProcessedVideoResult | null>;
+    /**
+     * Set cached processing result
+     */
+    set(src: string, options: Partial<EnhancedVideoProps>, result: ProcessedVideoResult): Promise<void>;
+    /**
+     * Clear the entire video cache
+     */
+    clear(): Promise<void>;
+    /**
+     * Update cache configuration
+     */
+    updateConfig(config: Partial<VideoCacheConfig>): void;
+}
 /**
  * Get cached video processing result
  */
@@ -12,21 +53,3 @@ export declare function setCachedVideoResult(src: string, options: Partial<Enhan
  * 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 {
-  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

@@ -1,21 +1,3 @@
-// Re-export types for convenience
-export type {
-  EnhancedVideoProps,
-  ProcessedVideoResult,
-  TsVideosConfig,
-  VideoQualityPreset,
-  VideoPlatformPreset,
-  TranscodeConfig,
-  TranscodeResult,
-  ThumbnailResult,
-  HLSResult,
-  DASHResult,
-  StreamingConfig,
-  StreamingQualityLevel,
-  PosterGenerationConfig,
-  SpriteSheetConfig,
-  WaveformConfig,
-} from '../../types';
 /**
  * STX Media - Video Processor
  *
@@ -27,3 +9,4 @@ export { processVideo, analyzeVideo } from './transcoder';
 export { generatePoster, generateThumbnails, generateSpriteSheet } from './thumbnail';
 export { generateHLSManifest, generateDASHManifest } from './streaming';
 export { getCachedVideoResult, setCachedVideoResult, clearVideoCache, VideoProcessorCache } from './cache';
+export type { EnhancedVideoProps, ProcessedVideoResult, TsVideosConfig, VideoQualityPreset, VideoPlatformPreset, TranscodeConfig, TranscodeResult, ThumbnailResult, HLSResult, DASHResult, StreamingConfig, StreamingQualityLevel, PosterGenerationConfig, SpriteSheetConfig, WaveformConfig, } from '../../types';

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

@@ -1,19 +1,26 @@
+/**
+ * STX Media - Video Streaming Manifest Generation
+ *
+ * Generate HLS and DASH manifests for adaptive streaming.
+ *
+ * @module media/video/processor/streaming
+ */
 import type { HLSResult, DASHResult, StreamingQualityLevel } from '../../types';
+/**
+ * Default streaming quality levels
+ */
+export declare const DEFAULT_STREAMING_QUALITIES: StreamingQualityLevel[];
 /**
  * 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>;
+    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[];
+    segmentDuration?: number;
+    minBufferTime?: number;
+}): Promise<DASHResult | null>;

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

@@ -1,3 +1,10 @@
+/**
+ * STX Media - Video Thumbnail Generation
+ *
+ * Generate poster images, thumbnails, and sprite sheets from video.
+ *
+ * @module media/video/processor/thumbnail
+ */
 import type { ThumbnailResult, PosterGenerationConfig, SpriteSheetConfig } from '../../types';
 /**
  * Generate poster/thumbnail from video at specific timestamp
@@ -7,23 +14,22 @@ export declare function generatePoster(src: string, options: PosterGenerationCon
  * 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[]>;
+    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
  */
-// eslint-disable-next-line pickier/no-unused-vars
 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
+    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

@@ -1,3 +1,10 @@
+/**
+ * STX Media - Video Transcoder
+ *
+ * Wraps ts-videos for video transcoding and analysis.
+ *
+ * @module media/video/processor/transcoder
+ */
 import type { EnhancedVideoProps, ProcessedVideoResult, TsVideosConfig } from '../../types';
 /**
  * Analyze video to get metadata
@@ -6,4 +13,7 @@ export declare function analyzeVideo(src: string): Promise<ProcessedVideoResult[
 /**
  * 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>;
+export declare function processVideo(src: string, options: Partial<EnhancedVideoProps>, config: TsVideosConfig, onProgress?: (progress: {
+    percentage: number;
+    stage: string;
+}) => void): Promise<ProcessedVideoResult>;

package/dist/method-spoofing.d.ts

@@ -1,3 +1,10 @@
+/**
+ * Form Method Spoofing for stx templates
+ *
+ * Similar to Laravel's @method directive, this allows specifying
+ * HTTP methods like PUT, PATCH, DELETE in HTML forms which only
+ * support GET and POST.
+ */
 /**
  * Generate a method spoofing input field
  */

package/dist/middleware.d.ts

@@ -1,3 +1,63 @@
+/**
+ * Middleware Module
+ *
+ * Provides a middleware system for pre/post-processing templates.
+ * Middleware can transform template content before or after directive processing.
+ *
+ * ## Middleware Lifecycle
+ *
+ * 1. **Before (pre-processing)**: Runs before any directives are processed.
+ *    Use for raw template transformation, content injection, or validation.
+ *
+ * 2. **After (post-processing)**: Runs after all directives are processed.
+ *    Use for output transformation, minification, or final validation.
+ *
+ * ## Middleware Definition
+ *
+ * ```typescript
+ * interface Middleware {
+ *   name: string                              // Unique identifier
+ *   timing: 'before' | 'after'                // When to run
+ *   handler: (
+ *     template: string,                       // Current template content
+ *     context: Record<string, any>,           // Template context
+ *     filePath: string,                       // Path to template file
+ *     options: StxOptions                     // Processing options
+ *   ) => string | Promise<string>             // Modified template
+ * }
+ * ```
+ *
+ * ## Configuration Example
+ *
+ * ```typescript
+ * // stx.config.ts
+ * export default {
+ *   middleware: [
+ *     {
+ *       name: 'minify-html',
+ *       timing: 'after',
+ *       handler: (template) => template.replace(/\\s+/g, ' ')
+ *     },
+ *     {
+ *       name: 'inject-timestamp',
+ *       timing: 'before',
+ *       handler: (template, ctx) => {
+ *         ctx.buildTime = new Date().toISOString()
+ *         return template
+ *       }
+ *     }
+ *   ]
+ * }
+ * ```
+ *
+ * ## Error Handling
+ *
+ * - Middleware errors are caught and logged (in debug mode)
+ * - A visual error message is injected into the output when debug is enabled
+ * - Processing continues with remaining middleware even if one fails
+ *
+ * @module middleware
+ */
 import type { StxOptions } from './types';
 /**
  * Process middleware registered in the application.

package/dist/owned-routes.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Which same-origin paths the SPA router actually owns (stacksjs/stx#1864).
+ *
+ * With `interceptAllLinks` — hardcoded as the base default on the serve path —
+ * the router claimed EVERY same-origin relative anchor. `shouldIntercept()`
+ * filtered on protocol, target and a few opt-out attributes and had no notion
+ * of a route table, so a link to a non-page endpoint got fetched, failed to
+ * swap, and then fell back to a real navigation. The endpoint was hit twice:
+ *
+ *     Fetch     503  /api/auth/github/redirect
+ *     Document  503  /api/auth/github/redirect
+ *
+ * on an endpoint whose whole job is minting OAuth state. Worse, when such an
+ * endpoint returns a successful cross-origin redirect, `fetch` follows it and
+ * the router swaps a third-party document into the container.
+ *
+ * The only escape was `data-no-router`, which removes the anchor from routing
+ * entirely — one reporting app carries 17 of them, and every new link has to
+ * remember whether it needs one.
+ *
+ * The missing concept is a manifest of owned paths, which the file router
+ * already has. This ships the compiled matchers to the client so interception
+ * asks "is this a page I can render?" instead of "is this same-origin?".
+ *
+ * Regex SOURCES are shipped rather than patterns because the client runtime is
+ * a template literal (see CLAUDE.md item 41) — re-implementing the pattern
+ * compiler in there would mean maintaining a second matcher, in a file where
+ * every backslash has to be doubled, that must agree with this one forever.
+ *
+ * @module owned-routes
+ */
+/**
+ * Serialised matchers for every route the router can render.
+ *
+ * Empty when nothing could be discovered — callers MUST treat that as "unknown"
+ * and leave interception alone, never as "owns nothing". Shipping an empty list
+ * as authoritative would disable SPA navigation for a whole site, which is a
+ * far worse failure than the double-fetch this fixes.
+ */
+export declare function getOwnedRouteMatchers(pagesDir?: string): Promise<string[]>;
+/** Drop the memo, for tests and for a dev server that added a page. */
+export declare function clearOwnedRoutesCache(): void;

package/dist/owned-routes.js

@@ -0,0 +1,26 @@
+import { createRouter } from "./router.js";
+import { loadStxConfig } from "./config.js";
+const _cache = new Map;
+export async function getOwnedRouteMatchers(pagesDir) {
+  let dir = pagesDir;
+  if (!dir)
+    try {
+      dir = (await loadStxConfig())?.pagesDir || "pages";
+    } catch {
+      dir = "pages";
+    }
+  const key = dir, cached = _cache.get(key);
+  if (cached)
+    return cached;
+  let sources = [];
+  try {
+    sources = createRouter(".", { pagesDir: key }).map((route) => route.regex.source).filter(Boolean);
+  } catch {
+    sources = [];
+  }
+  _cache.set(key, sources);
+  return sources;
+}
+export function clearOwnedRoutesCache() {
+  _cache.clear();
+}

package/dist/page-meta.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Reading `definePageMeta({ … })` out of a template's source.
+ *
+ * `PageMeta.layout` was part of the public type and appeared in
+ * `definePageMeta`'s own documentation example, but no code path read it. A
+ * page declaring `definePageMeta({ layout: 'app' })` type-checked, looked like
+ * the idiomatic declaration, and rendered with no layout at all
+ * (stacksjs/stx#1879).
+ *
+ * The cost was not just the missing layout. With no working typed way to say
+ * "this page belongs to the app layout group", pages hand-wrote
+ * `<meta name="stx-layout" content="app">` — a copy of a marker stx emits
+ * itself. The router's full-document-vs-fragment swap decision hinges on that
+ * string, so a page asserting a group it does not belong to is a routing
+ * hazard, not a cosmetic one.
+ *
+ * The extraction lives here because four separate regexes over
+ * `definePageMeta` had accumulated across `ssg.ts`, `page-response.ts` and
+ * `bun-plugin`'s serve path, each recognising a slightly different subset.
+ *
+ * @module page-meta
+ */
+/**
+ * Parse the first `definePageMeta({ … })` call in `source`.
+ *
+ * Object literals only — the call is read statically, before any script has
+ * run, so a computed argument cannot be resolved and returns `null` rather
+ * than half a result.
+ */
+export declare function extractPageMetaFromSource(source: string): Record<string, any> | null;
+/**
+ * The layout a page declares, if any.
+ *
+ * `false` is meaningful and distinct from "not declared" — it means the same
+ * as `@nolayout`, so it must survive as `false` rather than collapsing into
+ * `undefined`.
+ */
+export declare function pageMetaLayout(meta: Record<string, any> | null | undefined): string | false | undefined;

package/dist/page-meta.js

@@ -0,0 +1,16 @@
+export function extractPageMetaFromSource(source) {
+  const match = source.match(/\bdefinePageMeta\s*\(\s*(\{[\s\S]*?\})\s*\)/m);
+  if (!match)
+    return null;
+  try {
+    return Function(`return ${match[1]}`)();
+  } catch {
+    return null;
+  }
+}
+export function pageMetaLayout(meta) {
+  const layout = meta?.layout;
+  if (layout === !1)
+    return !1;
+  return typeof layout === "string" && layout.trim() ? layout.trim() : void 0;
+}

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

@@ -1,3 +1,32 @@
+/**
+ * Directive Parser
+ *
+ * Provides utilities for parsing directives with proper handling of
+ * nested structures, balanced tags, and expressions.
+ *
+ * @module parser/directive-parser
+ */
+export interface DirectiveMatch {
+    fullMatch: string;
+    name: string;
+    params: string;
+    content: string;
+    start: number;
+    end: number;
+}
+export interface ConditionalBranch {
+    type: 'if' | 'elseif' | 'else';
+    condition?: string;
+    content: string;
+    start: number;
+    end: number;
+}
+export interface ParsedConditional {
+    fullMatch: string;
+    branches: ConditionalBranch[];
+    start: number;
+    end: number;
+}
 /**
  * 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 }
@@ -7,9 +36,24 @@
  * messages pointing at the source location of a malformed `@if(`).
  */
 export declare function extractParenthesizedExpression(source: string, startPos: number): {
-  expression: string
-  endPos: number
+    expression: string;
+    endPos: number;
 } | null;
+/**
+ * Structured variant of `extractParenthesizedExpression` — returns either a
+ * successful parse or a `{ ok: false, reason, pos }` record explaining the
+ * failure. Use this when emitting user-facing errors ("missing opening
+ * paren", "unclosed paren at column N", etc.).
+ */
+export type ExtractParenResult = {
+    ok: true;
+    expression: string;
+    endPos: number;
+} | {
+    ok: false;
+    reason: 'missing-open-paren' | 'unclosed-paren';
+    pos: number;
+};
 export declare function extractParenthesizedExpressionDetailed(source: string, startPos: number): ExtractParenResult;
 /**
  * Whether `pos` in `source` falls INSIDE an HTML tag (`<...>`) — i.e. the nearest
@@ -57,51 +101,19 @@ export declare function findIfBlocks(source: string): ParsedConditional[];
  * @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 interface SwitchCase {
+    type: 'case' | 'default';
+    value?: string;
+    content: string;
 }
-export declare interface ParsedSwitch {
-  fullMatch: string
-  expression: string
-  cases: SwitchCase[]
-  start: number
-  end: number
+export interface ParsedSwitch {
+    fullMatch: string;
+    expression: string;
+    cases: SwitchCase[];
+    start: number;
+    end: number;
 }
-/**
- * Structured variant of `extractParenthesizedExpression` — returns either a
- * successful parse or a `{ ok: false, reason, pos }` record explaining the
- * failure. Use this when emitting user-facing errors ("missing opening
- * paren", "unclosed paren at column N", etc.).
- */
-export type ExtractParenResult = | { ok: true, expression: string, endPos: number }
-  | { ok: false, reason: 'missing-open-paren' | 'unclosed-paren', pos: number }
+export declare function parseSwitchBlock(source: string, startPos: number): ParsedSwitch | null;