@stacksjs/stx 0.2.10 → 0.2.12

package/dist/inline-assets.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Check if a URL is external (http, https, or protocol-relative)
+ */
+export declare function isExternalUrl(url: string): boolean;
+/**
+ * Resolve an inline asset path relative to the template file.
+ *
+ * @param assetPath - The path from the src/href attribute
+ * @param templateDir - Directory containing the template
+ * @param filePath - Full path to the template file
+ * @returns Resolved absolute path, or null if not found
+ */
+export declare function resolveInlinePath(assetPath: string, templateDir: string, _filePath: string): string | null;
+/**
+ * Automatically inline local JS/CSS files.
+ *
+ * This function handles:
+ * - `<script src="./file.js"></script>` → `<script>...file contents...</script>`
+ * - `<link href="./file.css" rel="stylesheet">` → `<style>...file contents...</style>`
+ *
+ * Only local/relative paths are inlined. External URLs (http://, https://, //) are left as-is.
+ *
+ * @param template - The template string to process
+ * @param filePath - Path to the current template file (for resolving relative paths)
+ * @param dependencies - Set to track included file dependencies
+ * @returns Template with local assets inlined
+ */
+export declare function processInlineAssets(template: string, filePath: string, dependencies: Set<string>): Promise<string>;

package/dist/internal-markdown.d.ts

@@ -8,10 +8,6 @@ export declare function parseFrontmatter(content: string): FrontmatterResult;
  * Simple implementation that handles common markdown patterns
  */
 export declare function parseMarkdown(content: string, options?: MarkdownOptions): string;
-/**
- * Internal markdown utilities to replace ts-md dependency
- * Provides frontmatter parsing and markdown to HTML conversion
- */
 export declare interface FrontmatterResult {
   data: Record<string, unknown>
   content: string

package/dist/jsx-runtime.d.ts

@@ -88,4 +88,5 @@ export declare interface VNode {
   ref?: string | ((el: any) => void) | null
 }
 /** Function component type */
+// eslint-disable-next-line pickier/no-unused-vars
 export type ComponentFunction = (props: Record<string, any>) => VNode | string | null;

package/dist/keep-alive.d.ts

@@ -36,6 +36,7 @@ export declare function onActivated(callback: (detail: { key: string; keepAliveI
  * Use in client-side scripts.
  */
 export declare function onDeactivated(callback: (detail: { key: string; keepAliveId: string }) => void): void;
+/* eslint-disable prefer-const, style/max-statements-per-line, no-super-linear-backtracking, regexp/no-unused-capturing-group */
 /**
  * STX Keep-Alive
  *

package/dist/manifest.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Generate a build manifest from compiled pages and assets.
+ */
+export declare function generateManifest(routes: ManifestRoute[], assets: ManifestAssets, outputDir: string): BuildManifest;
+/**
+ * Write the manifest to disk.
+ */
+export declare function writeManifest(manifest: BuildManifest, outputDir: string): void;
+/**
+ * Load and validate a build manifest from disk.
+ * Returns null if the manifest doesn't exist or is invalid.
+ */
+export declare function loadManifest(outputDir: string): BuildManifest | null;
+/**
+ * A route entry in the build manifest.
+ */
+export declare interface ManifestRoute {
+  pattern: string
+  compiledPath: string
+  fragmentPath: string
+  isDynamic: boolean
+  hasParams: boolean
+}
+/**
+ * Asset entries in the build manifest.
+ */
+export declare interface ManifestAssets {
+  runtime: string
+  router: string
+  css?: string
+}
+/**
+ * The complete build manifest.
+ */
+export declare interface BuildManifest {
+  version: 1
+  buildTime: string
+  routes: ManifestRoute[]
+  assets: ManifestAssets
+  outputDir: string
+}

package/dist/markdown.d.ts

@@ -2,6 +2,7 @@
  * Process markdown directives in templates
  * Converts markdown content to HTML
  */
+// eslint-disable-next-line pickier/no-unused-vars
 export declare function processMarkdownDirectives(template: string, context: Record<string, any>, filePath?: string): Promise<string>;
 /**
  * Custom directive handler for markdown

package/dist/media/client/blur-up.d.ts

@@ -45,6 +45,7 @@ export declare function generateBlurUpRuntime(): string;
  * Generate CSS for blur-up effect
  */
 export declare function generateBlurUpCSS(): string;
+/* eslint-disable prefer-const, style/max-statements-per-line, no-super-linear-backtracking, regexp/no-unused-capturing-group */
 /**
  * STX Media - Client-Side Blur-Up Animation
  *

package/dist/media/client/lazy-load.d.ts

@@ -50,6 +50,7 @@ export declare function disconnectObserver(observer: IntersectionObserver): void
  * Generate the client-side lazy loading runtime script
  */
 export declare function generateLazyLoadRuntime(): string;
+/* eslint-disable prefer-const, style/max-statements-per-line, no-super-linear-backtracking, regexp/no-unused-capturing-group */
 /**
  * STX Media - Client-Side Lazy Loading
  *

package/dist/media/client/upload-handler.d.ts

@@ -30,6 +30,7 @@ export declare function generateVideoPreview(file: File): Promise<string>;
  * Generate client-side upload handler runtime
  */
 export declare function generateUploadRuntime(): string;
+/* eslint-disable prefer-const, style/max-statements-per-line, no-super-linear-backtracking, regexp/no-unused-capturing-group */
 /**
  * STX Media - Client-Side Upload Handler
  *

package/dist/media/shared/cache.d.ts

@@ -9,6 +9,7 @@ export declare function setCached<T>(src: string, options: Record<string, unknow
 /**
  * Clear cache for a specific source
  */
+// eslint-disable-next-line pickier/no-unused-vars
 export declare function clearCacheForSource(src: string, type: 'image' | 'video', config?: CacheConfig): Promise<void>;
 /**
  * Clear entire cache
@@ -17,6 +18,7 @@ export declare function clearCache(type: 'image' | 'video' | 'all', config?: Cac
 /**
  * Get cache statistics
  */
+// eslint-disable-next-line pickier/no-unused-vars
 export declare function getCacheStats(config?: CacheConfig): Promise<{
   memoryEntries: number
   diskEntries: { image: number; video: number }

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

@@ -35,6 +35,7 @@ export declare function renderVideoComponent(props: VideoProps | EnhancedVideoPr
 /**
  * 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

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

@@ -16,6 +16,7 @@ export declare function generateThumbnails(src: string, options: {
 /**
  * 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

package/dist/misc-directives.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Process @json directive to output JSON
+ */
+export declare function processJsonDirective(template: string, context: Record<string, any>): string;
+/**
+ * Process @once directive blocks.
+ * Primary deduplication is handled by processIncludes (context.__onceStore).
+ * This function only strips remaining @once/@endonce tags, keeping content.
+ */
+export declare function processOnceDirective(template: string): string;
+/**
+ * Process @memo directive — memoize template subtrees.
+ *
+ * Two shapes are supported:
+ *
+ * 1. Attribute form on an element:
+ *      <div @memo="[count(), name()]">Expensive content</div>
+ *    Transforms to `data-stx-memo="[count(), name()]"`. The signals runtime
+ *    skips re-processing elements whose deps haven't changed.
+ *
+ * 2. Blade-style block form wrapping arbitrary markup:
+ *      @memo([])
+ *        <section>...marketing content...</section>
+ *      @endmemo
+ *    The block is transformed by injecting `data-stx-memo` onto the first
+ *    opening tag inside the block (or wrapping in a <div> if the contents
+ *    don't start with a single element). Both `@memo(...)` and `@endmemo`
+ *    are stripped from the output.
+ */
+export declare function processMemoDirective(template: string): string;
+/**
+ * Process ref attributes for DOM element references (Vue-style).
+ *
+ * Transforms:
+ *   <input ref="inputRef" />
+ *   <input @ref="inputRef" />
+ *
+ * Into:
+ *   <input data-stx-ref="inputRef" />
+ *
+ * The client-side runtime will automatically bind these to ref objects.
+ */
+export declare function processRefAttributes(template: string): string;
+/**
+ * Add x-cloak to HTML elements that contain unresolved {{ }} expressions.
+ * These expressions were preserved for client-side evaluation (signals, loop vars, etc.).
+ * x-cloak hides them until the JS runtime processes and reveals them — prevents FOUC.
+ */
+export declare function addCloakToUnresolvedExpressions(html: string): string;

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

@@ -1,11 +1,16 @@
 /**
  * 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 }
+ *
+ * Returns `null` for the legacy callers; use `extractParenthesizedExpressionDetailed`
+ * when you need to know WHY extraction failed (helpful for directive error
+ * messages pointing at the source location of a malformed `@if(`).
  */
 export declare function extractParenthesizedExpression(source: string, startPos: number): {
   expression: string
   endPos: number
 } | null;
+export declare function extractParenthesizedExpressionDetailed(source: string, startPos: number): ExtractParenResult;
 /**
  * Find the matching end tag for a directive, handling nested instances
  *
@@ -77,3 +82,11 @@ export declare interface ParsedSwitch {
   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 }

package/dist/performance-utils.d.ts

@@ -126,7 +126,9 @@ export declare interface BudgetViolation {
 /**
  * Performance budget violation handler type
  */
+// eslint-disable-next-line pickier/no-unused-vars
 export type BudgetViolationHandler = (violation: BudgetViolation) => void;
+/* eslint-disable prefer-const, style/max-statements-per-line, no-super-linear-backtracking, regexp/no-unused-capturing-group, pickier/no-unused-vars */
 /**
  * Performance optimization utilities for stx
  */

package/dist/placeholder.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Reset the placeholder counter and registry (for testing / between builds).
+ */
+export declare function resetPlaceholders(): void;
+/**
+ * Create a unique placeholder token and register the expression.
+ *
+ * @param type - The type of placeholder ('expr' for expressions, 'cond' for conditionals)
+ * @param expr - The original expression (stored in the registry for serve-time hydration)
+ * @returns A unique placeholder token string
+ */
+export declare function createPlaceholder(type: 'expr' | 'cond' | 'raw', expr: string): string;
+/**
+ * Get the registered placeholder map (all tokens created since last reset).
+ * Used by the template compiler to build the CompiledTemplate.placeholders field.
+ */
+export declare function getPlaceholderRegistry(): PlaceholderMap;
+/**
+ * Extract all placeholder tokens from compiled HTML.
+ *
+ * @returns A map of token → expression info
+ */
+export declare function extractPlaceholders(html: string): PlaceholderMap;
+/**
+ * Replace placeholder tokens with evaluated values.
+ * Uses simple string replacement for maximum performance.
+ *
+ * @param html - The compiled HTML with placeholder tokens
+ * @param values - Map of placeholder token → resolved value
+ * @returns HTML with all placeholders replaced
+ */
+export declare function replacePlaceholders(html: string, values: Map<string, string>): string;
+/**
+ * Check if HTML contains any placeholder tokens.
+ */
+export declare function hasPlaceholders(html: string): boolean;
+/**
+ * A map of placeholder tokens to their original expressions.
+ */
+export declare interface PlaceholderMap {
+  [token: string]: {
+    type: 'expr' | 'cond' | 'raw'
+    expression: string
+  }
+}

package/dist/plugin-system.d.ts

@@ -1,8 +1,22 @@
 import type { CustomDirective, StxOptions } from './types';
 /**
- * Create a plugin with type safety
+ * Define an stx plugin with type safety.
+ *
+ * Usage:
+ * ```typescript
+ * import { definePlugin } from 'stx'
+ *
+ * export default definePlugin({
+ *   name: 'my-plugin',
+ *   components: './components',
+ *   functions: './functions',
+ *   setup(options, stx) {
+ *     stx.addRoute('/api/custom', handler)
+ *   },
+ * })
+ * ```
  */
-export declare function definePlugin(plugin: StxPlugin): StxPlugin;
+export declare function definePlugin(config: StxPlugin): StxPlugin;
 /**
  * Create a simple directive plugin
  */
@@ -75,6 +89,22 @@ export declare interface StxPlugin {
   registerFilters?: () => Record<string, (value: unknown, ...args: unknown[]) => unknown>
   onRegister?: (options: StxOptions) => void | Promise<void>
   onUnregister?: () => void | Promise<void>
+  components?: string
+  functions?: string
+  stores?: string
+  pages?: string
+  middleware?: string
+  setup?: (options: Record<string, any>, stx: PluginSetupContext) => void | Promise<void>
+}
+/**
+ * Context passed to plugin setup() function
+ */
+export declare interface PluginSetupContext {
+  addDirective: (directive: CustomDirective) => void
+  addRoute: (path: string, handler: (req: Request) => Response | Promise<Response>) => void
+  addMiddleware: (middleware: any) => void
+  pluginDir: string
+  config: StxOptions
 }
 /**
  * Directive type identifier for beforeDirective/afterDirective hooks

package/dist/process.d.ts

@@ -1 +1,11 @@
-
+import { processJsonDirective, processOnceDirective } from './misc-directives';
+import { validateClientScript } from './script-validation';
+import type { StxOptions } from './types';
+/**
+ * Process all template directives with enhanced error handling and performance monitoring
+ */
+export declare function processDirectives(template: string, context: Record<string, any>, filePath: string, options: StxOptions, dependencies: Set<string>): Promise<string>;
+// Re-export public API from extracted modules (preserves backwards compatibility)
+export { injectRouterScript } from './runtime-injection';
+export { processJsonDirective, processOnceDirective } from './misc-directives';
+export { validateClientScript } from './script-validation';

package/dist/production-builder.d.ts

@@ -0,0 +1,42 @@
+import { type ManifestAssets } from './manifest';
+/**
+ * Build the stx application for production.
+ *
+ * Produces a `.output/` directory with:
+ * - `public/__stx/` — fingerprinted runtime and router JS
+ * - `public/assets/` — bundled CSS
+ * - `public/<user files>` — copied verbatim from the project's `publicDir`
+ *   (default: `public/`). Source images, fonts, robots.txt, sitemap.xml, etc.
+ * - `server/pages/` — compiled template JSON files
+ * - `server/fragments/` — SPA navigation fragments
+ * - `manifest.json` — route map and asset hashes
+ *
+ * Reads `stx.config.ts` once at the start for `publicDir`, `componentsDir`,
+ * `layoutsDir`, `partialsDir`, and `app.head`. Direct option overrides take
+ * precedence over the config file.
+ */
+export declare function buildForProduction(options?: ProductionBuildOptions): Promise<ProductionBuildResult>;
+/**
+ * Production build configuration.
+ *
+ * Most fields are optional and fall back to `stx.config.ts` if not provided.
+ * Resolution order for each field: explicit option → config file → default.
+ */
+export declare interface ProductionBuildOptions {
+  root?: string
+  outputDir?: string
+  debug?: boolean
+  componentsDir?: string
+  partialsDir?: string
+  layoutsDir?: string
+  publicDir?: string
+}
+/**
+ * Result of a production build.
+ */
+export declare interface ProductionBuildResult {
+  pageCount: number
+  assets: ManifestAssets
+  outputDir: string
+  duration: number
+}

package/dist/production-server.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Start the production server.
+ *
+ * Serves pre-built pages from .output/ with minimal per-request work:
+ * - Static assets: served from disk with immutable cache headers
+ * - SPA fragments: served from pre-extracted HTML files
+ * - Static pages: served directly (zero processing)
+ * - Dynamic pages: hydrated with request-time data
+ */
+export declare function startProductionServer(options?: ProductionServerOptions): Promise<{ port: number, stop: () => void }>;
+/**
+ * Production server configuration.
+ */
+export declare interface ProductionServerOptions {
+  outputDir?: string
+  port?: number
+  onRequest?: (req: Request) => Response | Promise<Response> | null | Promise<null>
+  apiRoutes?: Record<string, (req: Request) => Response | Promise<Response>>
+}

package/dist/props.d.ts

@@ -164,6 +164,7 @@ export type ExtractPropTypes<T extends PropsDefinition<unknown>> = {
       : unknown
 }
 /** Event handler type */
+// eslint-disable-next-line pickier/no-unused-vars
 export type EventHandler<T = unknown> = (payload: T) => void;
 /** Emit function type */
 export type EmitFn<E extends Record<string, unknown>> = <K extends keyof E>(