sibujs 4.12.0 → 4.13.1

package/dist/build.d.ts

@@ -1,199 +1,93 @@
-/** A version 3 source map, as bundlers accept it from a transform hook. */
-interface SourceMapV3 {
-    version: 3;
-    file?: string;
-    sources: string[];
-    sourcesContent: string[];
-    names: string[];
-    mappings: string;
-}
-
-/**
- * Official Vite plugin for SibuJS.
- * Provides optimized builds, automatic component detection, and development enhancements.
- */
-
-interface SibuVitePluginOptions {
-    /** Enable HMR support for SibuJS components */
-    hmr?: boolean;
-    /**
-     * Annotate calls to side-effect-free sibujs factories (`tagFactory`,
-     * `context`, ...) as pure for tree-shaking. Only direct calls to names
-     * imported from sibujs are annotated. Default: true.
-     */
-    pureAnnotations?: boolean;
-    /** Component file patterns to watch */
-    include?: string[];
-    /** File patterns to exclude */
-    exclude?: string[];
-    /**
-     * Enable dev mode features (devtools, debug logging). When omitted it is
-     * derived from Vite's own command/mode (`vite build` is production unless
-     * `--mode development`; `vite serve` is development), falling back to
-     * `NODE_ENV` only when the plugin is driven outside Vite.
-     */
-    devMode?: boolean;
-    /**
-     * Replace provably static tag-factory calls (`div({ class: "x" }, "text")`)
-     * with `staticTemplate(...)` markup. Default: **false**, in every mode.
-     *
-     * Off by default because it is not a win: `staticTemplate` parses its markup
-     * on every call, which is slower than the tag factory's `createElement` +
-     * `setAttribute` for the single-element calls that can be proven static, and
-     * the proof has to exclude every prop the factory treats specially (URL and
-     * style sanitizing, IDL-only booleans, event and ref props). The analysis is
-     * conservative and correct, but a correct pessimization is not a sane
-     * default. It previously defaulted to on and rewrote non-sibujs calls
-     * (`db.select({...})`) and the template compiler's output into invalid code.
-     */
-    staticOptimize?: boolean;
-    /**
-     * Compile `html` tagged templates (imported from sibujs) at build time.
-     * Default: true in production builds. Most templates become direct DOM
-     * construction; the rest are parsed at build time and rendered by the
-     * runtime's own executor, so no template is parsed in the browser (the sole
-     * exception is a template consisting of one invalid escape sequence).
-     */
-    compileTemplates?: boolean;
-}
-/** The subset of Vite's config environment / resolved config the plugin reads. */
-interface ViteModeInfo {
-    command?: string;
-    mode?: string;
-}
 /**
- * Vite plugin configuration for SibuJS projects.
- * Returns a Vite-compatible plugin object.
+ * Bundle size analysis utilities for SibuJS.
+ * Provides tools to analyze, estimate, and report on bundle sizes
+ * for SibuJS projects.
  */
-declare function sibuVitePlugin(options?: SibuVitePluginOptions): {
-    name: string;
-    enforce?: "pre" | "post";
-    config?: (userConfig?: unknown, env?: ViteModeInfo) => Record<string, unknown>;
-    configResolved?: (config: ViteModeInfo) => void;
-    transform?: (code: string, id: string) => {
-        code: string;
-        map: SourceMapV3;
-    } | null;
-    handleHotUpdate?: (ctx: {
-        file: string;
-        modules: unknown[];
-    }) => void;
-};
 /**
- * Generate an optimized Vite configuration for SibuJS projects.
- */
-declare function createViteConfig(options?: {
-    /** Entry point */
-    entry?: string;
-    /** Output directory */
-    outDir?: string;
-    /** Enable SSR mode */
-    ssr?: boolean;
-    /** Additional Vite config overrides */
-    overrides?: Record<string, unknown>;
-}): Record<string, unknown>;
-
-/**
- * Webpack plugin configuration for SibuJS projects.
- * Provides build optimization, pure annotations, and development enhancements.
+ * Known approximate sizes (in bytes, minified + gzipped) for SibuJS modules.
+ * These estimates are based on the typical compiled output of each module
+ * and are useful for pre-build size budgeting.
  */
-interface SibuWebpackPluginOptions {
-    /**
-     * NOT applied by the plugin — pure annotations under webpack need a loader
-     * rule, and webpack loaders must be resolvable module files. Setting this to
-     * `true` logs how to add the one-line loader instead of silently doing
-     * nothing:
-     *
-     * ```js
-     * // sibu-pure-loader.cjs
-     * module.exports = require("sibujs/build").createPureAnnotationsLoader();
-     *
-     * // webpack.config.js
-     * module: {
-     *   rules: [{ test: /\.[cm]?[jt]sx?$/, exclude: /node_modules/, use: "./sibu-pure-loader.cjs" }],
-     * }
-     * ```
-     *
-     * The rule this plugin used to push named a loader that does not exist
-     * (`__sibu_inline_loader__`), which failed every build with the default
-     * options; the option is kept so existing configs keep compiling.
-     */
-    pureAnnotations?: boolean;
-    /**
-     * Enable dev mode features (devtools, debug logging). When omitted it is
-     * derived from webpack's own resolved `mode`: `development` is dev,
-     * `production` and an unset mode (webpack's default is production) are not,
-     * and `mode: "none"` falls back to `NODE_ENV`.
-     */
-    devMode?: boolean;
-}
+declare const moduleSizes: Record<string, number>;
 /**
- * Webpack plugin configuration helper for SibuJS.
- * Returns webpack-compatible plugin and loader configurations.
+ * Analyze module sizes and dependencies.
  *
- * Usage:
- * ```js
- * const { sibuWebpackPlugin } = require('sibujs/build');
- * module.exports = {
- *   plugins: [sibuWebpackPlugin()],
- * };
+ * Takes a record of module names to their source code and computes
+ * size statistics for each module and the total bundle.
+ *
+ * @param modules - A map of module names to their source code strings
+ * @returns Analysis results with sizes, sorted rankings, and a report generator
+ *
+ * @example
+ * ```ts
+ * import { analyzeBundle } from 'sibu/src/build/analyzer';
+ *
+ * const result = analyzeBundle({
+ *   'app.ts': appSourceCode,
+ *   'components/Header.ts': headerSourceCode,
+ *   'components/Footer.ts': footerSourceCode,
+ * });
+ *
+ * console.log(result.report());
+ * // Total: 12.5 KB
+ * // app.ts: 8.2 KB (65.6%)
+ * // components/Header.ts: 2.8 KB (22.4%)
+ * // components/Footer.ts: 1.5 KB (12.0%)
  * ```
  */
-/** Minimal webpack compiler interface for plugin compatibility. */
-interface WebpackCompiler {
-    hooks?: Record<string, {
-        tap: (name: string, callback: (...args: unknown[]) => void) => void;
-    } | undefined>;
-    options: {
-        module?: {
-            rules?: unknown[];
-        };
-        resolve?: {
-            mainFields?: string[];
-        };
-        plugins?: unknown[];
-        [key: string]: unknown;
-    };
-    [key: string]: unknown;
-}
-declare function sibuWebpackPlugin(options?: SibuWebpackPluginOptions): {
-    /** Plugin name */
-    name: string;
-    /** Apply function for webpack plugin API */
-    apply: (compiler: WebpackCompiler) => void;
+declare function analyzeBundle(modules: Record<string, string>): {
+    /** Total bundle size in bytes */
+    totalSize: number;
+    /** Size per module in bytes */
+    moduleSizes: Record<string, number>;
+    /** Modules sorted by size (largest first) */
+    sorted: Array<{
+        name: string;
+        size: number;
+        percentage: number;
+    }>;
+    /** Format as human-readable report */
+    report: () => string;
 };
 /**
- * Create a standalone webpack loader function for pure annotation injection.
+ * Estimate the impact of importing specific SibuJS modules.
+ * Based on known approximate sizes of each module (minified + gzipped).
  *
- * Webpack resolves loaders by path, so wrap it in a loader module and point a
- * rule at that file:
- * ```js
- * // sibu-pure-loader.cjs
- * const { createPureAnnotationsLoader } = require("sibujs/build");
- * module.exports = createPureAnnotationsLoader();
- * ```
- */
-declare function createPureAnnotationsLoader(): (source: string) => string;
-/**
- * Generate Webpack configuration for SibuJS projects.
+ * This is useful for understanding the cost of specific imports
+ * before building, enabling informed decisions about which features to use.
  *
- * Usage:
- * ```js
- * const { createWebpackConfig } = require('sibujs/build');
- * module.exports = createWebpackConfig({
- *   entry: './src/index.ts',
- *   mode: 'production',
- * });
+ * @param imports - Array of module paths to estimate (e.g., ['core/signal', 'core/html'])
+ * @returns Estimated size information with breakdown
+ *
+ * @example
+ * ```ts
+ * import { estimateImportSize } from 'sibu/src/build/analyzer';
+ *
+ * // Estimate cost of a minimal SibuJS app
+ * const estimate = estimateImportSize([
+ *   'core/html',
+ *   'core/mount',
+ *   'core/signal',
+ *   'core/effect',
+ *   'reactivity/track',
+ *   'reactivity/batch',
+ * ]);
+ *
+ * console.log(estimate.formatted);
+ * // Estimated bundle size: 3.17 KB (minified + gzipped)
+ * //   core/html: 1.76 KB
+ * //   core/effect: 0.34 KB
+ * //   ...
  * ```
  */
-declare function createWebpackConfig(options?: {
-    /** Entry point file */
-    entry?: string;
-    /** Output directory path */
-    outputPath?: string;
-    /** Build mode */
-    mode?: "development" | "production";
-}): Record<string, unknown>;
+declare function estimateImportSize(imports: string[]): {
+    /** Total estimated size in bytes */
+    estimated: number;
+    /** Size breakdown per module */
+    breakdown: Record<string, number>;
+    /** Human-readable formatted output */
+    formatted: string;
+};
 
 /**
  * CDN distribution utilities for SibuJS.
@@ -284,6 +178,48 @@ declare function generateImportMap(baseUrl?: string): {
     toScriptTag: () => string;
 };
 
+/**
+ * Build-time compiler for SibuJS html tagged templates.
+ *
+ * Transforms:
+ *   html`<div class=${cls}><span>${() => count()}</span></div>`
+ *
+ * Into a module-level construction function plus a call that passes the
+ * template's expressions in their original order:
+ *
+ *   __sibujs$t0((cls), (() => count()))
+ *   ...
+ *   function __sibujs$t0(v0, v1) { ...direct DOM construction... }
+ *
+ * A compiled template builds exactly the DOM the runtime `html` parser would;
+ * any template the compiler cannot reproduce exactly is left to the runtime.
+ * The contract, the parser port and the list of templates left to the runtime
+ * are documented in templateCompiler.ts.
+ */
+interface CompileResult {
+    /** The transformed source code, or null if nothing was compiled */
+    code: string | null;
+    /** Tag names of the elements the compiled templates create */
+    usedTags: Set<string>;
+    /** Whether any compiled template creates SVG-namespace elements */
+    usesSvg: boolean;
+    /** Number of templates compiled */
+    compiledCount: number;
+    /** Number of sibujs `html` templates deliberately left to the runtime parser */
+    skippedCount: number;
+}
+/**
+ * Compile the sibujs `html` tagged templates in a module to direct DOM
+ * construction. The returned code is self-contained: it carries the aliased
+ * imports and helpers the compiled templates need, appended at the end of the
+ * module (imports are hoisted, and appending keeps every original line where
+ * it was — each compiled template also keeps the line breaks it spanned).
+ *
+ * Returns `code: null` when nothing was compiled — including when the file
+ * cannot be scanned with confidence.
+ */
+declare function compileHtmlTemplates(code: string): CompileResult;
+
 /**
  * TypeScript declaration map utilities for SibuJS.
  * Provides tsconfig helpers and declaration generation support
@@ -344,95 +280,60 @@ declare function validateTsConfig(config: Record<string, unknown>): {
 };
 
 /**
- * Bundle size analysis utilities for SibuJS.
- * Provides tools to analyze, estimate, and report on bundle sizes
- * for SibuJS projects.
- */
-/**
- * Known approximate sizes (in bytes, minified + gzipped) for SibuJS modules.
- * These estimates are based on the typical compiled output of each module
- * and are useful for pre-build size budgeting.
+ * IDE extension support for SibuJS.
+ * Provides metadata and utilities for VS Code and other IDE integrations.
  */
-declare const moduleSizes: Record<string, number>;
 /**
- * Analyze module sizes and dependencies.
- *
- * Takes a record of module names to their source code and computes
- * size statistics for each module and the total bundle.
- *
- * @param modules - A map of module names to their source code strings
- * @returns Analysis results with sizes, sorted rankings, and a report generator
- *
- * @example
- * ```ts
- * import { analyzeBundle } from 'sibu/src/build/analyzer';
- *
- * const result = analyzeBundle({
- *   'app.ts': appSourceCode,
- *   'components/Header.ts': headerSourceCode,
- *   'components/Footer.ts': footerSourceCode,
- * });
- *
- * console.log(result.report());
- * // Total: 12.5 KB
- * // app.ts: 8.2 KB (65.6%)
- * // components/Header.ts: 2.8 KB (22.4%)
- * // components/Footer.ts: 1.5 KB (12.0%)
- * ```
+ * Component metadata for IDE IntelliSense.
  */
-declare function analyzeBundle(modules: Record<string, string>): {
-    /** Total bundle size in bytes */
-    totalSize: number;
-    /** Size per module in bytes */
-    moduleSizes: Record<string, number>;
-    /** Modules sorted by size (largest first) */
-    sorted: Array<{
+interface ComponentMeta {
+    name: string;
+    description: string;
+    props: Array<{
+        name: string;
+        type: string;
+        required: boolean;
+        default?: string;
+        description: string;
+    }>;
+    events?: Array<{
         name: string;
-        size: number;
-        percentage: number;
+        description: string;
     }>;
-    /** Format as human-readable report */
-    report: () => string;
-};
+}
 /**
- * Estimate the impact of importing specific SibuJS modules.
- * Based on known approximate sizes of each module (minified + gzipped).
- *
- * This is useful for understanding the cost of specific imports
- * before building, enabling informed decisions about which features to use.
- *
- * @param imports - Array of module paths to estimate (e.g., ['core/signal', 'core/html'])
- * @returns Estimated size information with breakdown
- *
- * @example
- * ```ts
- * import { estimateImportSize } from 'sibu/src/build/analyzer';
- *
- * // Estimate cost of a minimal SibuJS app
- * const estimate = estimateImportSize([
- *   'core/html',
- *   'core/mount',
- *   'core/signal',
- *   'core/effect',
- *   'reactivity/track',
- *   'reactivity/batch',
- * ]);
- *
- * console.log(estimate.formatted);
- * // Estimated bundle size: 3.17 KB (minified + gzipped)
- * //   core/html: 1.76 KB
- * //   core/effect: 0.34 KB
- * //   ...
- * ```
+ * SibuJS component registry for IDE auto-completion.
+ * Returns metadata about all built-in SibuJS exports.
  */
-declare function estimateImportSize(imports: string[]): {
-    /** Total estimated size in bytes */
-    estimated: number;
-    /** Size breakdown per module */
-    breakdown: Record<string, number>;
-    /** Human-readable formatted output */
-    formatted: string;
+declare function getComponentMetadata(): ComponentMeta[];
+/**
+ * Generate VS Code snippets for SibuJS.
+ */
+declare function generateVSCodeSnippets(): Record<string, {
+    prefix: string;
+    body: string[];
+    description: string;
+}>;
+/**
+ * Generate a language configuration for SibuJS files.
+ * Provides bracket matching, comment toggling, and auto-close pairs.
+ */
+declare function generateLanguageConfig(): {
+    comments: {
+        lineComment: string;
+        blockComment: [string, string];
+    };
+    brackets: [string, string][];
+    autoClosingPairs: Array<{
+        open: string;
+        close: string;
+    }>;
 };
+/**
+ * Generate type stubs for common SibuJS patterns.
+ * Useful for IDE auto-import suggestions.
+ */
+declare function generateTypeStubs(): Record<string, string>;
 
 /**
  * ESLint plugin configuration for SibuJS best practices.
@@ -494,60 +395,202 @@ declare function generateEslintConfig(options?: {
 }): Record<string, unknown>;
 
 /**
- * IDE extension support for SibuJS.
- * Provides metadata and utilities for VS Code and other IDE integrations.
+ * Build-time pre-rendering for single-page apps.
+ *
+ * An SPA built with `createRouter({ mode: "history" })` ships an empty
+ * `<div id="app">`: crawlers and link-preview bots see no content, and every
+ * route shares one `<title>`. A render server fixes that, but many apps are
+ * served as static files by a backend that is not Node. This renders each
+ * listed route ONCE, at build time, and writes it as a static HTML file.
+ *
+ * How a route is rendered:
+ *
+ *  1. The app's own client entry is built a second time as a Node module (a
+ *     Vite SSR build of the same entry, with the same config).
+ *  2. In a fresh worker thread — one per route, so module state such as the
+ *     router singleton never leaks between routes — a jsdom document is created
+ *     from the BUILT `index.html` at the route's URL and registered as the
+ *     global DOM, and the entry is imported. It runs exactly as in a browser.
+ *  3. The page is serialized once it has settled: every `fetch`, every promise
+ *     passed to `prerenderWait()`, the router's initial navigation and its lazy
+ *     route chunks have finished, and the DOM has been quiet for `settle` ms.
+ *  4. The document — rendered body, and the head the router produced for the
+ *     route (title, description, canonical, Open Graph) — is written to
+ *     `<outDir>/<route>/index.html`. The built `<script>` tags are kept, so the
+ *     browser loads the client, which takes over (see the AGENTS.md recipe).
+ *
+ * Everything here is Node-only and loaded lazily, so importing `sibujs/build`
+ * elsewhere never pulls in a Node built-in.
+ */
+/** One route to pre-render. */
+interface PrerenderRoute {
+    /** The route URL, e.g. `"/pricing"` (a query string is allowed). */
+    path: string;
+    /** Output file, relative to the build output dir. Default: `<path>/index.html`. */
+    output?: string;
+}
+interface PrerenderOptions {
+    /** Routes to render. */
+    routes: Array<string | PrerenderRoute>;
+    /**
+     * The client entry module, relative to the Vite root. Default: the first
+     * `<script type="module" src>` in the source `index.html`.
+     */
+    entry?: string;
+    /**
+     * Origin of the URL each route is rendered at. Relative `fetch()` URLs
+     * resolve against it, and `location` reports it. Default `"http://localhost"`.
+     */
+    origin?: string;
+    /** Per-route time limit in ms before the build fails. Default 15000. */
+    timeout?: number;
+    /** How long the DOM must stay quiet, with nothing pending, before serializing. Default 50 ms. */
+    settle?: number;
+    /**
+     * Where to keep an untouched copy of the SPA shell (the built `index.html`
+     * before `/` is pre-rendered over it), for the backend's fallback route.
+     * Default `"200.html"`; `false` to skip it.
+     */
+    shell?: string | false;
+    /** Routes rendered at the same time. Default 4. */
+    concurrency?: number;
+}
+/** What the pre-renderer needs to know about the Vite build that just ran. */
+interface PrerenderBuildContext {
+    /** Vite root (absolute). */
+    root: string;
+    /** Build output dir (absolute). */
+    outDir: string;
+    /** The Vite config file used for the client build, if any. */
+    configFile?: string | false;
+    /** Vite mode. */
+    mode?: string;
+}
+/** One rendered route. */
+interface PrerenderResult {
+    route: string;
+    file: string;
+    ms: number;
+}
+/** Environment variable marking the nested SSR build, so it does not pre-render again. */
+declare const PRERENDER_CHILD_ENV = "SIBU_PRERENDER_CHILD";
+/**
+ * Find the client entry of a Vite app from its source `index.html`.
+ * @internal
  */
+declare function findEntryInHtml(html: string): string | null;
 /**
- * Component metadata for IDE IntelliSense.
+ * The output file for a route, relative to the output dir. Refuses paths that
+ * could escape it.
+ * @internal
  */
-interface ComponentMeta {
-    name: string;
-    description: string;
-    props: Array<{
-        name: string;
-        type: string;
-        required: boolean;
-        default?: string;
-        description: string;
-    }>;
-    events?: Array<{
-        name: string;
-        description: string;
-    }>;
-}
+declare function outputFileFor(route: PrerenderRoute): string;
 /**
- * SibuJS component registry for IDE auto-completion.
- * Returns metadata about all built-in SibuJS exports.
+ * Absolute destination of `file` inside `outDir`, refusing anything that
+ * resolves outside it. The last line of defence at the write boundary, so a
+ * path `outputFileFor` let through can still never escape.
+ * @internal
  */
-declare function getComponentMetadata(): ComponentMeta[];
+declare function resolveInsideOutDir(path: {
+    resolve: (...p: string[]) => string;
+    relative: (a: string, b: string) => string;
+    isAbsolute: (p: string) => boolean;
+}, outDir: string, file: string): string;
 /**
- * Generate VS Code snippets for SibuJS.
+ * Pre-render `options.routes` into `ctx.outDir`. Called by
+ * `sibuVitePlugin({ prerender })` after the client build; callable directly
+ * from a build script too.
+ *
+ * @param options Routes and rendering options.
+ * @param ctx The finished client build.
+ * @returns One entry per written file.
+ * @throws When a route fails to render, throws, or does not settle in time.
  */
-declare function generateVSCodeSnippets(): Record<string, {
-    prefix: string;
-    body: string[];
-    description: string;
-}>;
+declare function prerender(options: PrerenderOptions, ctx: PrerenderBuildContext): Promise<PrerenderResult[]>;
 /**
- * Generate a language configuration for SibuJS files.
- * Provides bracket matching, comment toggling, and auto-close pairs.
+ * The file an export-map entry points at for an ES-module `import`.
+ * @internal
  */
-declare function generateLanguageConfig(): {
-    comments: {
-        lineComment: string;
-        blockComment: [string, string];
-    };
-    brackets: [string, string][];
-    autoClosingPairs: Array<{
-        open: string;
-        close: string;
-    }>;
-};
+declare function esmEntryOf(entry: unknown): string | undefined;
+
 /**
- * Generate type stubs for common SibuJS patterns.
- * Useful for IDE auto-import suggestions.
+ * Vite plugin for automatic route-based code splitting.
+ * Scans a routes directory and generates lazy-loaded route definitions.
  */
-declare function generateTypeStubs(): Record<string, string>;
+interface RouteSplittingOptions {
+    /** Directory containing route files (default: "src/routes") */
+    routesDir?: string;
+    /** Glob patterns to exclude */
+    exclude?: string[];
+    /** Chunk name prefix (default: "route-") */
+    chunkPrefix?: string;
+}
+interface RouteEntry {
+    /** URL path pattern (e.g., "/users/:id") */
+    path: string;
+    /** Import path relative to project root */
+    importPath: string;
+    /** Generated chunk name */
+    chunkName: string;
+    /** Whether route has dynamic segments */
+    isDynamic: boolean;
+}
+/**
+ * Convert a file path within the routes directory to a URL pattern.
+ *
+ * Conventions:
+ * - index.ts -> /
+ * - about.ts -> /about
+ * - users/[id].ts -> /users/:id
+ * - blog/[...slug].ts -> /blog/*
+ * - _layout.ts -> skipped (layout file)
+ * - _middleware.ts -> skipped
+ */
+declare function fileToRoute(relativePath: string): string | null;
+/**
+ * Generate route entries from scanned files.
+ */
+declare function buildRouteEntries(files: string[], chunkPrefix: string): RouteEntry[];
+/**
+ * Vite plugin for automatic route-based code splitting.
+ *
+ * Scans the routes directory and generates a virtual module `virtual:sibu-routes`
+ * that exports lazy-loaded route definitions compatible with Sibu's router.
+ *
+ * @example
+ * ```ts
+ * // vite.config.ts
+ * import { sibuVitePlugin } from "sibujs/build";
+ * import { sibuRouteSplitting } from "sibujs/build";
+ *
+ * export default {
+ *   plugins: [sibuVitePlugin(), sibuRouteSplitting()],
+ * };
+ *
+ * // In your app:
+ * import { routes } from "virtual:sibu-routes";
+ * import { setRoutes } from "sibujs/plugins";
+ * setRoutes(routes);
+ * ```
+ */
+declare function sibuRouteSplitting(options?: RouteSplittingOptions): {
+    name: string;
+    enforce: "pre";
+    resolveId: (id: string) => string | undefined;
+    load: (id: string) => Promise<string | undefined>;
+    handleHotUpdate?: (ctx: {
+        file: string;
+        server: {
+            moduleGraph: {
+                invalidateModule: (mod: unknown) => void;
+                getModuleById: (id: string) => unknown;
+            };
+            ws: {
+                send: (msg: unknown) => void;
+            };
+        };
+    }) => void;
+};
 
 /**
  * Static analysis utilities for SibuJS build-time optimizations.
@@ -602,132 +645,228 @@ interface StaticAnalysisResult {
  *   div({ class: "card", id: "main" }, "Hello")
  *
  * And identifies them as candidates for:
- *   staticTemplate('<div class="card" id="main">Hello</div>')
- *
- * Only calls to tag factories imported from "sibujs" in this file are
- * considered, and only when every argument is provably static.
- */
-declare function analyzeStaticTemplates(code: string): StaticAnalysisResult;
-
-/**
- * Build-time compiler for SibuJS html tagged templates.
- *
- * Transforms:
- *   html`<div class=${cls}><span>${() => count()}</span></div>`
- *
- * Into a module-level construction function plus a call that passes the
- * template's expressions in their original order:
- *
- *   __sibujs$t0((cls), (() => count()))
- *   ...
- *   function __sibujs$t0(v0, v1) { ...direct DOM construction... }
- *
- * A compiled template builds exactly the DOM the runtime `html` parser would;
- * any template the compiler cannot reproduce exactly is left to the runtime.
- * The contract, the parser port and the list of templates left to the runtime
- * are documented in templateCompiler.ts.
- */
-interface CompileResult {
-    /** The transformed source code, or null if nothing was compiled */
-    code: string | null;
-    /** Tag names of the elements the compiled templates create */
-    usedTags: Set<string>;
-    /** Whether any compiled template creates SVG-namespace elements */
-    usesSvg: boolean;
-    /** Number of templates compiled */
-    compiledCount: number;
-    /** Number of sibujs `html` templates deliberately left to the runtime parser */
-    skippedCount: number;
-}
-/**
- * Compile the sibujs `html` tagged templates in a module to direct DOM
- * construction. The returned code is self-contained: it carries the aliased
- * imports and helpers the compiled templates need, appended at the end of the
- * module (imports are hoisted, and appending keeps every original line where
- * it was — each compiled template also keeps the line breaks it spanned).
+ *   staticTemplate('<div class="card" id="main">Hello</div>')
  *
- * Returns `code: null` when nothing was compiled — including when the file
- * cannot be scanned with confidence.
+ * Only calls to tag factories imported from "sibujs" in this file are
+ * considered, and only when every argument is provably static.
  */
-declare function compileHtmlTemplates(code: string): CompileResult;
+declare function analyzeStaticTemplates(code: string): StaticAnalysisResult;
+
+/** A version 3 source map, as bundlers accept it from a transform hook. */
+interface SourceMapV3 {
+    version: 3;
+    file?: string;
+    sources: string[];
+    sourcesContent: string[];
+    names: string[];
+    mappings: string;
+}
 
 /**
- * Vite plugin for automatic route-based code splitting.
- * Scans a routes directory and generates lazy-loaded route definitions.
+ * Official Vite plugin for SibuJS.
+ * Provides optimized builds, automatic component detection, and development enhancements.
  */
-interface RouteSplittingOptions {
-    /** Directory containing route files (default: "src/routes") */
-    routesDir?: string;
-    /** Glob patterns to exclude */
+
+interface SibuVitePluginOptions {
+    /** Enable HMR support for SibuJS components */
+    hmr?: boolean;
+    /**
+     * Annotate calls to side-effect-free sibujs factories (`tagFactory`,
+     * `context`, ...) as pure for tree-shaking. Only direct calls to names
+     * imported from sibujs are annotated. Default: true.
+     */
+    pureAnnotations?: boolean;
+    /** Component file patterns to watch */
+    include?: string[];
+    /** File patterns to exclude */
     exclude?: string[];
-    /** Chunk name prefix (default: "route-") */
-    chunkPrefix?: string;
+    /**
+     * Enable dev mode features (devtools, debug logging). When omitted it is
+     * derived from Vite's own command/mode (`vite build` is production unless
+     * `--mode development`; `vite serve` is development), falling back to
+     * `NODE_ENV` only when the plugin is driven outside Vite.
+     */
+    devMode?: boolean;
+    /**
+     * Replace provably static tag-factory calls (`div({ class: "x" }, "text")`)
+     * with `staticTemplate(...)` markup. Default: **false**, in every mode.
+     *
+     * Off by default because it is not a win: `staticTemplate` parses its markup
+     * on every call, which is slower than the tag factory's `createElement` +
+     * `setAttribute` for the single-element calls that can be proven static, and
+     * the proof has to exclude every prop the factory treats specially (URL and
+     * style sanitizing, IDL-only booleans, event and ref props). The analysis is
+     * conservative and correct, but a correct pessimization is not a sane
+     * default. It previously defaulted to on and rewrote non-sibujs calls
+     * (`db.select({...})`) and the template compiler's output into invalid code.
+     */
+    staticOptimize?: boolean;
+    /**
+     * Compile `html` tagged templates (imported from sibujs) at build time.
+     * Default: true in production builds. Most templates become direct DOM
+     * construction; the rest are parsed at build time and rendered by the
+     * runtime's own executor, so no template is parsed in the browser (the sole
+     * exception is a template consisting of one invalid escape sequence).
+     */
+    compileTemplates?: boolean;
+    /**
+     * Pre-render routes to static HTML after `vite build`, for an SPA served by
+     * a backend that cannot render it (SEO, link previews). Each route is run in
+     * a registered DOM (jsdom, which the app must install) and written to
+     * `dist/<route>/index.html` with its rendered body and its route head; the
+     * client then takes over with `hydrate()`. See `PrerenderOptions`.
+     *
+     * @example
+     * ```ts
+     * sibuVitePlugin({ prerender: { routes: ["/", "/cotizar", "/galeria"] } })
+     * ```
+     */
+    prerender?: PrerenderOptions;
 }
-interface RouteEntry {
-    /** URL path pattern (e.g., "/users/:id") */
-    path: string;
-    /** Import path relative to project root */
-    importPath: string;
-    /** Generated chunk name */
-    chunkName: string;
-    /** Whether route has dynamic segments */
-    isDynamic: boolean;
+/** The subset of Vite's config environment / resolved config the plugin reads. */
+interface ViteModeInfo {
+    command?: string;
+    mode?: string;
+    root?: string;
+    configFile?: string | false;
+    build?: {
+        outDir?: string;
+        ssr?: unknown;
+    };
 }
 /**
- * Convert a file path within the routes directory to a URL pattern.
- *
- * Conventions:
- * - index.ts -> /
- * - about.ts -> /about
- * - users/[id].ts -> /users/:id
- * - blog/[...slug].ts -> /blog/*
- * - _layout.ts -> skipped (layout file)
- * - _middleware.ts -> skipped
+ * Vite plugin configuration for SibuJS projects.
+ * Returns a Vite-compatible plugin object.
  */
-declare function fileToRoute(relativePath: string): string | null;
+declare function sibuVitePlugin(options?: SibuVitePluginOptions): {
+    name: string;
+    enforce?: "pre" | "post";
+    config?: (userConfig?: unknown, env?: ViteModeInfo) => Record<string, unknown>;
+    configResolved?: (config: ViteModeInfo) => void;
+    closeBundle?: () => Promise<void>;
+    transform?: (code: string, id: string) => {
+        code: string;
+        map: SourceMapV3;
+    } | null;
+    handleHotUpdate?: (ctx: {
+        file: string;
+        modules: unknown[];
+    }) => void;
+};
 /**
- * Generate route entries from scanned files.
+ * Generate an optimized Vite configuration for SibuJS projects.
  */
-declare function buildRouteEntries(files: string[], chunkPrefix: string): RouteEntry[];
+declare function createViteConfig(options?: {
+    /** Entry point */
+    entry?: string;
+    /** Output directory */
+    outDir?: string;
+    /** Enable SSR mode */
+    ssr?: boolean;
+    /** Additional Vite config overrides */
+    overrides?: Record<string, unknown>;
+}): Record<string, unknown>;
+
 /**
- * Vite plugin for automatic route-based code splitting.
- *
- * Scans the routes directory and generates a virtual module `virtual:sibu-routes`
- * that exports lazy-loaded route definitions compatible with Sibu's router.
- *
- * @example
- * ```ts
- * // vite.config.ts
- * import { sibuVitePlugin } from "sibujs/build";
- * import { sibuRouteSplitting } from "sibujs/build";
+ * Webpack plugin configuration for SibuJS projects.
+ * Provides build optimization, pure annotations, and development enhancements.
+ */
+interface SibuWebpackPluginOptions {
+    /**
+     * NOT applied by the plugin — pure annotations under webpack need a loader
+     * rule, and webpack loaders must be resolvable module files. Setting this to
+     * `true` logs how to add the one-line loader instead of silently doing
+     * nothing:
+     *
+     * ```js
+     * // sibu-pure-loader.cjs
+     * module.exports = require("sibujs/build").createPureAnnotationsLoader();
+     *
+     * // webpack.config.js
+     * module: {
+     *   rules: [{ test: /\.[cm]?[jt]sx?$/, exclude: /node_modules/, use: "./sibu-pure-loader.cjs" }],
+     * }
+     * ```
+     *
+     * The rule this plugin used to push named a loader that does not exist
+     * (`__sibu_inline_loader__`), which failed every build with the default
+     * options; the option is kept so existing configs keep compiling.
+     */
+    pureAnnotations?: boolean;
+    /**
+     * Enable dev mode features (devtools, debug logging). When omitted it is
+     * derived from webpack's own resolved `mode`: `development` is dev,
+     * `production` and an unset mode (webpack's default is production) are not,
+     * and `mode: "none"` falls back to `NODE_ENV`.
+     */
+    devMode?: boolean;
+}
+/**
+ * Webpack plugin configuration helper for SibuJS.
+ * Returns webpack-compatible plugin and loader configurations.
  *
- * export default {
- *   plugins: [sibuVitePlugin(), sibuRouteSplitting()],
+ * Usage:
+ * ```js
+ * const { sibuWebpackPlugin } = require('sibujs/build');
+ * module.exports = {
+ *   plugins: [sibuWebpackPlugin()],
  * };
- *
- * // In your app:
- * import { routes } from "virtual:sibu-routes";
- * import { setRoutes } from "sibujs/plugins";
- * setRoutes(routes);
  * ```
  */
-declare function sibuRouteSplitting(options?: RouteSplittingOptions): {
-    name: string;
-    enforce: "pre";
-    resolveId: (id: string) => string | undefined;
-    load: (id: string) => Promise<string | undefined>;
-    handleHotUpdate?: (ctx: {
-        file: string;
-        server: {
-            moduleGraph: {
-                invalidateModule: (mod: unknown) => void;
-                getModuleById: (id: string) => unknown;
-            };
-            ws: {
-                send: (msg: unknown) => void;
-            };
+/** Minimal webpack compiler interface for plugin compatibility. */
+interface WebpackCompiler {
+    hooks?: Record<string, {
+        tap: (name: string, callback: (...args: unknown[]) => void) => void;
+    } | undefined>;
+    options: {
+        module?: {
+            rules?: unknown[];
         };
-    }) => void;
+        resolve?: {
+            mainFields?: string[];
+        };
+        plugins?: unknown[];
+        [key: string]: unknown;
+    };
+    [key: string]: unknown;
+}
+declare function sibuWebpackPlugin(options?: SibuWebpackPluginOptions): {
+    /** Plugin name */
+    name: string;
+    /** Apply function for webpack plugin API */
+    apply: (compiler: WebpackCompiler) => void;
 };
+/**
+ * Create a standalone webpack loader function for pure annotation injection.
+ *
+ * Webpack resolves loaders by path, so wrap it in a loader module and point a
+ * rule at that file:
+ * ```js
+ * // sibu-pure-loader.cjs
+ * const { createPureAnnotationsLoader } = require("sibujs/build");
+ * module.exports = createPureAnnotationsLoader();
+ * ```
+ */
+declare function createPureAnnotationsLoader(): (source: string) => string;
+/**
+ * Generate Webpack configuration for SibuJS projects.
+ *
+ * Usage:
+ * ```js
+ * const { createWebpackConfig } = require('sibujs/build');
+ * module.exports = createWebpackConfig({
+ *   entry: './src/index.ts',
+ *   mode: 'production',
+ * });
+ * ```
+ */
+declare function createWebpackConfig(options?: {
+    /** Entry point file */
+    entry?: string;
+    /** Output directory path */
+    outputPath?: string;
+    /** Build mode */
+    mode?: "development" | "production";
+}): Record<string, unknown>;
 
-export { type CompileResult, type ComponentMeta, type LintViolation, type RouteSplittingOptions, type SibuVitePluginOptions, type SibuWebpackPluginOptions, type StaticAnalysisResult, analyzeBundle, analyzeStaticTemplates, buildRouteEntries, cdnUrls, compileHtmlTemplates, createPureAnnotationsLoader, createViteConfig, createWebpackConfig, estimateImportSize, fileToRoute, generateEslintConfig, generateImportMap, generateLanguageConfig, generateTsConfig, generateTypeStubs, generateVSCodeSnippets, getComponentMetadata, lintRules, lintSource, moduleSizes, registerGlobal, sibuRouteSplitting, sibuVitePlugin, sibuWebpackPlugin, umdWrapper, validateTsConfig };
+export { type CompileResult, type ComponentMeta, type LintViolation, PRERENDER_CHILD_ENV, type PrerenderBuildContext, type PrerenderOptions, type PrerenderResult, type PrerenderRoute, type RouteSplittingOptions, type SibuVitePluginOptions, type SibuWebpackPluginOptions, type StaticAnalysisResult, analyzeBundle, analyzeStaticTemplates, buildRouteEntries, cdnUrls, compileHtmlTemplates, createPureAnnotationsLoader, createViteConfig, createWebpackConfig, esmEntryOf, estimateImportSize, fileToRoute, findEntryInHtml, generateEslintConfig, generateImportMap, generateLanguageConfig, generateTsConfig, generateTypeStubs, generateVSCodeSnippets, getComponentMetadata, lintRules, lintSource, moduleSizes, outputFileFor, prerender, registerGlobal, resolveInsideOutDir, sibuRouteSplitting, sibuVitePlugin, sibuWebpackPlugin, umdWrapper, validateTsConfig };