@ohos-ports/stacksjs-stx 0.2.287-beta.0

package/dist/plugin-system.d.ts

@@ -0,0 +1,301 @@
+/**
+ * Plugin System for stx
+ *
+ * Provides a robust plugin architecture with lifecycle hooks for extending
+ * the template processing pipeline.
+ *
+ * ## Plugin Lifecycle
+ *
+ * Plugins can hook into various stages of template processing:
+ *
+ * 1. **beforeProcess** - Before any directive processing begins
+ * 2. **afterParse** - After template is parsed but before directives run
+ * 3. **beforeDirective** - Before each directive type is processed
+ * 4. **afterDirective** - After each directive type is processed
+ * 5. **beforeRender** - Before final output is generated
+ * 6. **afterRender** - After final output is generated
+ * 7. **onError** - When an error occurs during processing
+ *
+ * ## Example Plugin
+ *
+ * ```typescript
+ * const myPlugin: StxPlugin = {
+ *   name: 'my-plugin',
+ *   version: '1.0.0',
+ *
+ *   beforeProcess({ template, context }) {
+ *     // Add global variables
+ *     context.myPluginData = { initialized: true }
+ *     return { template, context }
+ *   },
+ *
+ *   registerDirectives() {
+ *     return [{
+ *       name: 'myDirective',
+ *       handler: (content, params) => content.toUpperCase(),
+ *       hasEndTag: true
+ *     }]
+ *   }
+ * }
+ * ```
+ *
+ * @module plugin-system
+ */
+import type { CustomDirective, StxOptions } from './types';
+/**
+ * Context passed to lifecycle hooks
+ */
+export interface PluginContext {
+    /** Current template content */
+    template: string;
+    /** Template context/variables */
+    context: Record<string, unknown>;
+    /** Source file path */
+    filePath: string;
+    /** Stx options */
+    options: StxOptions;
+    /** Dependencies tracked during processing */
+    dependencies: Set<string>;
+    /** Metadata for plugin communication */
+    metadata: Record<string, unknown>;
+}
+/**
+ * Result from a lifecycle hook
+ */
+export interface PluginHookResult {
+    /** Modified template (optional) */
+    template?: string;
+    /** Modified context (optional) */
+    context?: Record<string, unknown>;
+    /** Whether to skip further processing (optional) */
+    skip?: boolean;
+    /** Additional metadata to pass along */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Error context passed to onError hook
+ */
+export interface PluginErrorContext extends PluginContext {
+    /** The error that occurred */
+    error: Error;
+    /** Phase where error occurred */
+    phase: string;
+    /** Directive being processed (if applicable) */
+    directive?: string;
+}
+/**
+ * Directive type identifier for beforeDirective/afterDirective hooks
+ */
+export type DirectivePhase = 'comments' | 'escaped' | 'stacks' | 'layouts' | 'includes' | 'js' | 'ts' | 'custom' | 'components' | 'animation' | 'routes' | 'auth' | 'csrf' | 'method' | 'loops' | 'conditionals' | 'forms' | 'markdown' | 'i18n' | 'a11y' | 'seo' | 'expressions';
+/**
+ * Plugin definition interface
+ */
+export interface StxPlugin {
+    /** Unique plugin name */
+    name: string;
+    /** Plugin version (semver) */
+    version?: string;
+    /** Plugin description */
+    description?: string;
+    /** Plugin dependencies (other plugin names) */
+    dependencies?: string[];
+    /** Order priority (lower runs first, default: 100) */
+    priority?: number;
+    /**
+     * Called before any template processing begins.
+     * Use this to initialize plugin state or modify the initial template.
+     */
+    beforeProcess?: (ctx: PluginContext) => PluginHookResult | Promise<PluginHookResult> | void;
+    /**
+     * Called after the template is parsed but before directives are processed.
+     * Useful for template analysis or pre-processing.
+     */
+    afterParse?: (ctx: PluginContext) => PluginHookResult | Promise<PluginHookResult> | void;
+    /**
+     * Called before a specific directive type is processed.
+     * @param phase - The directive phase being processed
+     * @param ctx - Plugin context
+     */
+    beforeDirective?: (phase: DirectivePhase, ctx: PluginContext) => PluginHookResult | Promise<PluginHookResult> | void;
+    /**
+     * Called after a specific directive type is processed.
+     * @param phase - The directive phase that was processed
+     * @param ctx - Plugin context
+     */
+    afterDirective?: (phase: DirectivePhase, ctx: PluginContext) => PluginHookResult | Promise<PluginHookResult> | void;
+    /**
+     * Called before the final render output is generated.
+     */
+    beforeRender?: (ctx: PluginContext) => PluginHookResult | Promise<PluginHookResult> | void;
+    /**
+     * Called after the final render output is generated.
+     */
+    afterRender?: (ctx: PluginContext) => PluginHookResult | Promise<PluginHookResult> | void;
+    /**
+     * Called when an error occurs during processing.
+     * Can return a recovery template or rethrow the error.
+     */
+    onError?: (ctx: PluginErrorContext) => PluginHookResult | Promise<PluginHookResult> | void;
+    /**
+     * Register custom directives provided by this plugin.
+     * Called during plugin initialization.
+     */
+    registerDirectives?: () => CustomDirective[];
+    /**
+     * Register custom expression filters.
+     * Called during plugin initialization.
+     */
+    registerFilters?: () => Record<string, (value: unknown, ...args: unknown[]) => unknown>;
+    /**
+     * Called when the plugin is registered.
+     * Use for one-time initialization.
+     */
+    onRegister?: (options: StxOptions) => void | Promise<void>;
+    /**
+     * Called when the plugin is unregistered.
+     * Use for cleanup.
+     */
+    onUnregister?: () => void | Promise<void>;
+    /** Directory of .stx components — auto-registered, available in all templates */
+    /**
+     * Component directory, or directories.
+     *
+     * An array lets one package register several roots — @stacksjs/components
+     * ships src/ui and src/components as siblings (#1823).
+     */
+    components?: string | string[];
+    /** Directory of composable functions — importable via @/functions/ */
+    functions?: string;
+    /** Directory of store definitions — auto-registered */
+    stores?: string;
+    /** Directory of page templates — merged into file-based routing */
+    pages?: string;
+    /** Directory of route middleware */
+    middleware?: string;
+    /** Setup function called when plugin is loaded — receives options and stx context */
+    setup?: (options: Record<string, any>, stx: PluginSetupContext) => void | Promise<void>;
+}
+/**
+ * Context passed to plugin setup() function
+ */
+export interface PluginSetupContext {
+    /** Register a custom directive */
+    addDirective: (directive: CustomDirective) => void;
+    /** Register an API route handler */
+    addRoute: (path: string, handler: (req: Request) => Response | Promise<Response>) => void;
+    /** Register route middleware */
+    addMiddleware: (middleware: any) => void;
+    /** The resolved plugin directory path */
+    pluginDir: string;
+    /** The stx config */
+    config: StxOptions;
+}
+/**
+ * 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(config: StxPlugin): StxPlugin;
+/**
+ * Plugin manager that handles registration, lifecycle, and execution
+ */
+export declare class PluginManager {
+    private plugins;
+    private sortedPlugins;
+    private initialized;
+    /**
+     * Register a plugin
+     */
+    register(plugin: StxPlugin, options: StxOptions): Promise<void>;
+    /**
+     * Unregister a plugin
+     */
+    unregister(name: string): Promise<boolean>;
+    /**
+     * Get a registered plugin by name
+     */
+    get(name: string): StxPlugin | undefined;
+    /**
+     * Check if a plugin is registered
+     */
+    has(name: string): boolean;
+    /**
+     * Get all registered plugins (sorted by priority)
+     */
+    getAll(): StxPlugin[];
+    /**
+     * Get all custom directives from all plugins
+     */
+    getAllDirectives(): CustomDirective[];
+    /**
+     * Get all filters from all plugins
+     */
+    getAllFilters(): Record<string, (value: unknown, ...args: unknown[]) => unknown>;
+    /**
+     * Run beforeProcess hooks on all plugins
+     */
+    runBeforeProcess(ctx: PluginContext): Promise<PluginContext>;
+    /**
+     * Run afterParse hooks on all plugins
+     */
+    runAfterParse(ctx: PluginContext): Promise<PluginContext>;
+    /**
+     * Run beforeDirective hooks on all plugins
+     */
+    runBeforeDirective(phase: DirectivePhase, ctx: PluginContext): Promise<PluginContext>;
+    /**
+     * Run afterDirective hooks on all plugins
+     */
+    runAfterDirective(phase: DirectivePhase, ctx: PluginContext): Promise<PluginContext>;
+    /**
+     * Run beforeRender hooks on all plugins
+     */
+    runBeforeRender(ctx: PluginContext): Promise<PluginContext>;
+    /**
+     * Run afterRender hooks on all plugins
+     */
+    runAfterRender(ctx: PluginContext): Promise<PluginContext>;
+    /**
+     * Run onError hooks on all plugins
+     */
+    runOnError(ctx: PluginErrorContext): Promise<PluginContext | null>;
+    private sortPlugins;
+    private runHooks;
+    private runDirectiveHooks;
+}
+/**
+ * Global plugin manager instance
+ */
+export declare const pluginManager: PluginManager;
+/**
+ * Create a simple directive plugin
+ */
+export declare function createDirectivePlugin(name: string, directives: CustomDirective[], options?: Partial<Omit<StxPlugin, 'name' | 'registerDirectives'>>): StxPlugin;
+/**
+ * Create a simple filter plugin
+ */
+export declare function createFilterPlugin(name: string, filters: Record<string, (value: unknown, ...args: unknown[]) => unknown>, options?: Partial<Omit<StxPlugin, 'name' | 'registerFilters'>>): StxPlugin;
+/**
+ * Debug plugin that logs all lifecycle events
+ */
+export declare const debugPlugin: StxPlugin;
+/**
+ * Timing plugin that measures processing time
+ */
+export declare const timingPlugin: StxPlugin;
+/**
+ * Variables plugin that adds common variables to context
+ */
+export declare function createVariablesPlugin(variables: Record<string, unknown>): StxPlugin;

package/dist/plugin-system.js

@@ -0,0 +1,214 @@
+export function definePlugin(config) {
+  return config;
+}
+
+export class PluginManager {
+  plugins = new Map;
+  sortedPlugins = [];
+  initialized = !1;
+  async register(plugin, options) {
+    if (this.plugins.has(plugin.name))
+      throw Error(`Plugin "${plugin.name}" is already registered`);
+    if (plugin.dependencies) {
+      for (const dep of plugin.dependencies)
+        if (!this.plugins.has(dep))
+          throw Error(`Plugin "${plugin.name}" depends on "${dep}" which is not registered`);
+    }
+    this.plugins.set(plugin.name, plugin);
+    if (plugin.onRegister)
+      await plugin.onRegister(options);
+    this.sortPlugins();
+  }
+  async unregister(name) {
+    const plugin = this.plugins.get(name);
+    if (!plugin)
+      return !1;
+    for (const [otherName, otherPlugin] of this.plugins)
+      if (otherPlugin.dependencies?.includes(name))
+        throw Error(`Cannot unregister "${name}" because "${otherName}" depends on it`);
+    if (plugin.onUnregister)
+      await plugin.onUnregister();
+    this.plugins.delete(name);
+    this.sortPlugins();
+    return !0;
+  }
+  get(name) {
+    return this.plugins.get(name);
+  }
+  has(name) {
+    return this.plugins.has(name);
+  }
+  getAll() {
+    return [...this.sortedPlugins];
+  }
+  getAllDirectives() {
+    const directives = [];
+    for (const plugin of this.sortedPlugins)
+      if (plugin.registerDirectives)
+        directives.push(...plugin.registerDirectives());
+    return directives;
+  }
+  getAllFilters() {
+    const filters = {};
+    for (const plugin of this.sortedPlugins)
+      if (plugin.registerFilters)
+        Object.assign(filters, plugin.registerFilters());
+    return filters;
+  }
+  async runBeforeProcess(ctx) {
+    return this.runHooks("beforeProcess", ctx);
+  }
+  async runAfterParse(ctx) {
+    return this.runHooks("afterParse", ctx);
+  }
+  async runBeforeDirective(phase, ctx) {
+    return this.runDirectiveHooks("beforeDirective", phase, ctx);
+  }
+  async runAfterDirective(phase, ctx) {
+    return this.runDirectiveHooks("afterDirective", phase, ctx);
+  }
+  async runBeforeRender(ctx) {
+    return this.runHooks("beforeRender", ctx);
+  }
+  async runAfterRender(ctx) {
+    return this.runHooks("afterRender", ctx);
+  }
+  async runOnError(ctx) {
+    for (const plugin of this.sortedPlugins)
+      if (plugin.onError)
+        try {
+          const result = await plugin.onError(ctx);
+          if (result) {
+            if (result.template !== void 0)
+              ctx.template = result.template;
+            if (result.context)
+              ctx.context = { ...ctx.context, ...result.context };
+            if (result.metadata)
+              ctx.metadata = { ...ctx.metadata, ...result.metadata };
+            if (result.skip)
+              return ctx;
+          }
+        } catch (hookError) {
+          console.error(`Error in plugin "${plugin.name}" onError hook:`, hookError);
+        }
+    return null;
+  }
+  sortPlugins() {
+    this.sortedPlugins = Array.from(this.plugins.values()).sort((a, b) => (a.priority ?? 100) - (b.priority ?? 100));
+  }
+  async runHooks(hookName, ctx) {
+    const currentCtx = { ...ctx };
+    for (const plugin of this.sortedPlugins) {
+      const hook = plugin[hookName];
+      if (hook)
+        try {
+          const result = await hook(currentCtx);
+          if (result) {
+            if (result.template !== void 0)
+              currentCtx.template = result.template;
+            if (result.context)
+              currentCtx.context = { ...currentCtx.context, ...result.context };
+            if (result.metadata)
+              currentCtx.metadata = { ...currentCtx.metadata, ...result.metadata };
+            if (result.skip)
+              break;
+          }
+        } catch (error) {
+          console.error(`Error in plugin "${plugin.name}" ${hookName} hook:`, error);
+        }
+    }
+    return currentCtx;
+  }
+  async runDirectiveHooks(hookName, phase, ctx) {
+    const currentCtx = { ...ctx };
+    for (const plugin of this.sortedPlugins) {
+      const hook = plugin[hookName];
+      if (hook)
+        try {
+          const result = await hook(phase, currentCtx);
+          if (result) {
+            if (result.template !== void 0)
+              currentCtx.template = result.template;
+            if (result.context)
+              currentCtx.context = { ...currentCtx.context, ...result.context };
+            if (result.metadata)
+              currentCtx.metadata = { ...currentCtx.metadata, ...result.metadata };
+            if (result.skip)
+              break;
+          }
+        } catch (error) {
+          console.error(`Error in plugin "${plugin.name}" ${hookName} hook:`, error);
+        }
+    }
+    return currentCtx;
+  }
+}
+export const pluginManager = new PluginManager;
+export function createDirectivePlugin(name, directives, options = {}) {
+  return {
+    name,
+    ...options,
+    registerDirectives: () => directives
+  };
+}
+export function createFilterPlugin(name, filters, options = {}) {
+  return {
+    name,
+    ...options,
+    registerFilters: () => filters
+  };
+}
+export const debugPlugin = definePlugin({
+  name: "stx-debug",
+  version: "1.0.0",
+  description: "Logs all plugin lifecycle events for debugging",
+  priority: 0,
+  beforeProcess(ctx) {
+    console.log("[stx-debug] beforeProcess:", ctx.filePath);
+  },
+  afterParse(ctx) {
+    console.log("[stx-debug] afterParse:", ctx.template.length, "chars");
+  },
+  beforeDirective(phase, _ctx) {
+    console.log("[stx-debug] beforeDirective:", phase);
+  },
+  afterDirective(phase, _ctx) {
+    console.log("[stx-debug] afterDirective:", phase);
+  },
+  beforeRender(_ctx) {
+    console.log("[stx-debug] beforeRender");
+  },
+  afterRender(ctx) {
+    console.log("[stx-debug] afterRender:", ctx.template.length, "chars");
+  },
+  onError(ctx) {
+    console.error("[stx-debug] onError:", ctx.error.message, "in phase:", ctx.phase);
+  }
+}), timingPlugin = definePlugin({
+  name: "stx-timing",
+  version: "1.0.0",
+  description: "Measures template processing time",
+  priority: 1,
+  beforeProcess(ctx) {
+    ctx.metadata.startTime = performance.now();
+  },
+  afterRender(ctx) {
+    const startTime = ctx.metadata.startTime;
+    if (startTime) {
+      const duration = performance.now() - startTime;
+      console.log(`[stx-timing] Processing took ${duration.toFixed(2)}ms`);
+    }
+  }
+});
+export function createVariablesPlugin(variables) {
+  return definePlugin({
+    name: "stx-variables",
+    version: "1.0.0",
+    description: "Adds predefined variables to template context",
+    beforeProcess(ctx) {
+      return {
+        context: { ...ctx.context, ...variables }
+      };
+    }
+  });
+}

package/dist/plugin.d.ts

@@ -0,0 +1,3 @@
+import type { BunPlugin } from 'bun';
+export declare const plugin: BunPlugin;
+export default plugin;

package/dist/plugin.js

@@ -0,0 +1,174 @@
+import path from "node:path";
+import { buildWebComponents, cacheTemplate, checkCache, extractVariables, loadStxConfig, processDirectives } from "./index.js";
+import { devHelpers, errorLogger, safeExecuteAsync, StxFileError, StxRuntimeError } from "./error-handling.js";
+import { isDevelopment } from "./env.js";
+import { escapeHtml } from "./expressions.js";
+import { performanceMonitor } from "./performance-utils.js";
+import { injectRouterScript } from "./process.js";
+import { findSfcTemplateBlock } from "./sfc-template.js";
+export const plugin = {
+  name: "bun-plugin-stx",
+  async setup(build) {
+    const options = {
+      ...await loadStxConfig(),
+      ...build.config?.stx
+    }, allDependencies = new Set, webComponentsPath = options.webComponents?.enabled ? `./${path.relative(path.dirname(build.config?.outdir || "dist"), options.webComponents.outputDir || "dist/web-components")}` : "/web-components", builtComponents = [];
+    if (options.webComponents?.enabled)
+      try {
+        const components = await buildWebComponents(options, allDependencies);
+        builtComponents.push(...components);
+        if (options.debug && components.length > 0)
+          console.log(`Successfully built ${components.length} web components`);
+      } catch (error) {
+        console.error("Failed to build web components:", error);
+      }
+    build.onLoad({ filter: /\.stx$/ }, async ({ path: filePath }) => {
+      try {
+        const dependencies = new Set;
+        if (options.cache && options.cachePath) {
+          const cachedOutput = await checkCache(filePath, options);
+          if (cachedOutput) {
+            if (options.debug)
+              console.log(`Using cached version of ${filePath}`);
+            return {
+              contents: cachedOutput,
+              loader: "html"
+            };
+          }
+        }
+        const content = await safeExecuteAsync(() => Bun.file(filePath).text(), "", (error) => {
+          throw new StxFileError(`Failed to read stx file: ${filePath}`, filePath, void 0, void 0, `File read error: ${error.message}`);
+        });
+        if (!content)
+          throw new StxFileError(`stx file is empty: ${filePath}`, filePath);
+        const { scriptContent, templateContent, allScripts } = performanceMonitor.time("script-extraction", () => {
+          let workingContent = content;
+          const templateBlock = findSfcTemplateBlock(content);
+          if (templateBlock)
+            workingContent = templateBlock.content.trim();
+          const allScriptMatches = content.match(/<script\b[^>]*>[\s\S]*?<\/script>/gi) || [];
+          let serverScriptContent = "";
+          const clientScripts = [];
+          for (const scriptTag of allScriptMatches) {
+            const innerContent = scriptTag.match(/<script\b[^>]*>([\s\S]*?)<\/script>/i)?.[1] || "", attrsMatch = scriptTag.match(/<script\b([^>]*)>/i), attrs = attrsMatch ? attrsMatch[1] : "";
+            if (/\bserver\b/i.test(attrs))
+              serverScriptContent = innerContent;
+            else
+              clientScripts.push(scriptTag);
+          }
+          const templateContent = workingContent.replace(/<script\b[^>]*>[\s\S]*?<\/script>/gi, "");
+          return { scriptContent: serverScriptContent, templateContent, allScripts: clientScripts };
+        }), context = {
+          __filename: filePath,
+          __dirname: path.dirname(filePath),
+          __stx: {
+            webComponentsPath,
+            builtComponents
+          }
+        };
+        await safeExecuteAsync(() => extractVariables(scriptContent, context, filePath), void 0, (error) => {
+          const scriptError = new StxRuntimeError(`Script execution failed in ${filePath}: ${error.message}`, filePath, void 0, void 0, scriptContent.substring(0, 100));
+          errorLogger.log(scriptError, { filePath, scriptContent });
+          if (options.debug)
+            throw scriptError;
+        });
+        let output = await performanceMonitor.timeAsync("directive-processing", async () => {
+          return await processDirectives(templateContent, context, filePath, options, dependencies);
+        });
+        if (allScripts.length > 0) {
+          const { interpolateScriptsInTemplate } = await import("./expressions.js"), scriptsHtml = interpolateScriptsInTemplate(allScripts.join(`
+`), context), bodyCloseIdx = output.search(/<\/body>/i);
+          if (bodyCloseIdx !== -1)
+            output = output.slice(0, bodyCloseIdx) + scriptsHtml + `
+` + output.slice(bodyCloseIdx);
+          else
+            output += `
+${scriptsHtml}`;
+        }
+        output = await injectRouterScript(output);
+        dependencies.forEach((dep) => allDependencies.add(dep));
+        if (options.cache && options.cachePath) {
+          await cacheTemplate(filePath, output, dependencies, options);
+          if (options.debug)
+            console.log(`Cached template ${filePath} with ${dependencies.size} dependencies`);
+        }
+        return {
+          contents: output,
+          loader: "html"
+        };
+      } catch (error) {
+        const enhancedError = error instanceof Error ? error : new StxRuntimeError(`Plugin processing failed: ${String(error)}`, filePath);
+        errorLogger.log(enhancedError, { filePath, buildConfig: build.config });
+        devHelpers.logDetailedError(enhancedError, { filePath, plugin: "bun-plugin-stx" });
+        if (options.debug)
+          console.error("stx Plugin Error:", enhancedError);
+        const stxError = enhancedError, errorLine = stxError.line || null, errorContext = stxError.context || null;
+        return {
+          contents: options.debug || isDevelopment() ? `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>stx Rendering Error</title>
+  <style>
+    body { font-family: system-ui, -apple-system, sans-serif; max-width: 800px; margin: 40px auto; padding: 20px; line-height: 1.6; }
+    .error-header { color: #dc3545; border-left: 4px solid #dc3545; padding-left: 16px; margin-bottom: 24px; }
+    .error-details { background: #f8f9fa; border: 1px solid #dee2e6; border-radius: 8px; padding: 16px; margin: 16px 0; }
+    .error-code { background: #2d3748; color: #e2e8f0; padding: 16px; border-radius: 8px; overflow-x: auto; font-family: 'Monaco', 'Menlo', monospace; font-size: 14px; }
+    .help-section { background: #e3f2fd; border-left: 4px solid #2196f3; padding: 16px; margin-top: 24px; }
+    .file-path { font-family: monospace; background: #f1f3f4; padding: 2px 6px; border-radius: 4px; }
+  </style>
+</head>
+<body>
+  <div class="error-header">
+    <h1>stx Template Error</h1>
+    <p>An error occurred while processing your stx template.</p>
+  </div>
+
+  <div class="error-details">
+    <h3>Error Details</h3>
+    <p><strong>File:</strong> <span class="file-path">${escapeHtml(filePath)}</span></p>
+    <p><strong>Error:</strong> ${escapeHtml(enhancedError.message)}</p>
+    ${errorLine ? `<p><strong>Line:</strong> ${escapeHtml(String(errorLine))}</p>` : ""}
+    ${errorContext ? `<p><strong>Context:</strong> ${escapeHtml(String(errorContext))}</p>` : ""}
+  </div>
+
+  ${enhancedError.stack ? `
+  <div class="error-details">
+    <h3>Stack Trace</h3>
+    <pre class="error-code">${escapeHtml(enhancedError.stack)}</pre>
+  </div>` : ""}
+
+  <div class="help-section">
+    <h3>Troubleshooting Tips</h3>
+    <ul>
+      <li>Check the syntax of your stx directives (e.g., @if, @foreach)</li>
+      <li>Verify that all variables used in the template are properly defined</li>
+      <li>Ensure script tags have valid JavaScript/TypeScript syntax</li>
+      <li>Run <code>stx debug ${escapeHtml(path.basename(filePath))}</code> for detailed analysis</li>
+      <li>Enable debug mode in your stx config for more detailed error messages</li>
+    </ul>
+  </div>
+</body>
+</html>` : `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Error</title>
+  <style>
+    body { font-family: system-ui, -apple-system, sans-serif; max-width: 600px; margin: 80px auto; padding: 20px; text-align: center; color: #333; }
+  </style>
+</head>
+<body>
+  <h1>Something went wrong</h1>
+  <p>An internal error occurred. Please try again later.</p>
+</body>
+</html>`,
+          loader: "html"
+        };
+      }
+    });
+  }
+};
+export default plugin;