sibujs 4.5.0 → 4.7.0

package/dist/build.d.cts

@@ -1,37 +1,76 @@
+/** 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;
-    /** Enable automatic pure annotations for tree-shaking */
+    /**
+     * 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) */
+    /**
+     * 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;
-    /** Enable static template optimization (default: true in production) */
+    /**
+     * 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 to direct function calls (default: true in production) */
+    /**
+     * Compile `html` tagged templates (imported from sibujs) to direct DOM
+     * construction. Default: true in production builds. A template the compiler
+     * cannot reproduce exactly is left to the runtime parser.
+     */
     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.
- *
- * Note: This is a configuration helper. For full Vite plugin functionality,
- * users should install @sibu/vite-plugin (when available).
  */
 declare function sibuVitePlugin(options?: SibuVitePluginOptions): {
     name: string;
     enforce?: "pre" | "post";
-    config?: () => Record<string, unknown>;
+    config?: (userConfig?: unknown, env?: ViteModeInfo) => Record<string, unknown>;
+    configResolved?: (config: ViteModeInfo) => void;
     transform?: (code: string, id: string) => {
         code: string;
-        map?: unknown;
+        map: SourceMapV3;
     } | null;
     handleHotUpdate?: (ctx: {
         file: string;
@@ -57,9 +96,21 @@ declare function createViteConfig(options?: {
  * Provides build optimization, pure annotations, and development enhancements.
  */
 interface SibuWebpackPluginOptions {
-    /** Enable automatic pure annotations for tree-shaking */
+    /**
+     * Accepted for API compatibility; the plugin itself no longer injects a
+     * loader. Webpack loaders must be resolvable modules, and 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. To get pure annotations, reference a loader file that returns
+     * `createPureAnnotationsLoader()(source)`.
+     */
     pureAnnotations?: boolean;
-    /** Enable dev mode features (devtools, debug logging) */
+    /**
+     * 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;
 }
 /**
@@ -68,7 +119,7 @@ interface SibuWebpackPluginOptions {
  *
  * Usage:
  * ```js
- * const { sibuWebpackPlugin } = require('sibu/src/build/webpack');
+ * const { sibuWebpackPlugin } = require('sibujs/build');
  * module.exports = {
  *   plugins: [sibuWebpackPlugin()],
  * };
@@ -99,7 +150,14 @@ declare function sibuWebpackPlugin(options?: SibuWebpackPluginOptions): {
 };
 /**
  * Create a standalone webpack loader function for pure annotation injection.
- * Can be used directly in webpack module rules.
+ *
+ * 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;
 /**
@@ -107,7 +165,7 @@ declare function createPureAnnotationsLoader(): (source: string) => string;
  *
  * Usage:
  * ```js
- * const { createWebpackConfig } = require('sibu/src/build/webpack');
+ * const { createWebpackConfig } = require('sibujs/build');
  * module.exports = createWebpackConfig({
  *   entry: './src/index.ts',
  *   mode: 'production',
@@ -133,7 +191,7 @@ declare function createWebpackConfig(options?: {
  *
  * Usage (in a script tag):
  * ```html
- * <script src="https://unpkg.com/sibu@latest/dist/cdn.global.js"></script>
+ * <script src="https://unpkg.com/sibujs@latest/dist/cdn.global.js"></script>
  * <script>
  *   const { div, span, mount, signal } = window.Sibu;
  *   // Use SibuJS without a bundler
@@ -180,7 +238,7 @@ declare const cdnUrls: {
      * @example
      * ```ts
      * cdnUrls.scriptTag('jsdelivr', '1.0.0')
-     * // => '<script src="https://cdn.jsdelivr.net/npm/sibu@1.0.0/dist/cdn.global.js"></script>'
+     * // => '<script src="https://cdn.jsdelivr.net/npm/sibujs@1.0.0/dist/cdn.global.js"></script>'
      * ```
      */
     scriptTag: (provider?: "unpkg" | "jsdelivr" | "skypack", version?: string) => string;
@@ -190,7 +248,7 @@ declare const cdnUrls: {
  * Useful for browser-native ES modules without a bundler.
  *
  * Import maps allow browsers to resolve bare module specifiers like
- * `import { div } from 'sibu'` without a build step.
+ * `import { div } from 'sibujs'` without a build step.
  *
  * @param baseUrl - Base URL for module resolution (defaults to jsDelivr)
  * @returns An import map object with serialization helpers
@@ -202,7 +260,7 @@ declare const cdnUrls: {
  *
  * // Now you can use bare specifiers in module scripts:
  * // <script type="module">
- * //   import { div, mount } from 'sibu';
+ * //   import { div, mount } from 'sibujs';
  * // </script>
  * ```
  */
@@ -225,7 +283,7 @@ declare function generateImportMap(baseUrl?: string): {
  *
  * @example
  * ```ts
- * import { generateTsConfig } from 'sibu/src/build/declarations';
+ * import { generateTsConfig } from 'sibujs/build';
  * import { writeFileSync } from 'fs';
  *
  * const config = generateTsConfig({ outDir: './dist' });
@@ -253,7 +311,7 @@ declare function generateTsConfig(options?: {
  *
  * @example
  * ```ts
- * import { validateTsConfig } from 'sibu/src/build/declarations';
+ * import { validateTsConfig } from 'sibujs/build';
  * import { readFileSync } from 'fs';
  *
  * const tsconfig = JSON.parse(readFileSync('tsconfig.json', 'utf-8'));
@@ -479,7 +537,31 @@ declare function generateTypeStubs(): Record<string, string>;
 
 /**
  * Static analysis utilities for SibuJS build-time optimizations.
- * Detects tagFactory calls that can be converted to template cloning.
+ * Detects tag-factory calls that can be converted to template cloning.
+ *
+ * A candidate is replaced by `staticTemplate("<markup>")`, so the analysis
+ * must PROVE that parsing the markup yields exactly the element the tag
+ * factory would have built. The earlier regex version proved nothing: it
+ * matched method calls (`db.select({...})`), text inside strings and
+ * comments, silently dropped shorthand and spread props while still calling
+ * the call static, treated `"a" + x` as a literal, and rendered `false` as
+ * `disabled="false"`. Every one of those is a production-only bug.
+ *
+ * The rule now is: optimize only what is provably equivalent, and leave
+ * everything else untouched. Concretely a call qualifies only when
+ *   - the callee is a tag factory imported from "sibujs" (by any local alias),
+ *     called directly — never `obj.tag(...)` — and the name is not declared
+ *     or used anywhere in the file in a way that could shadow the import (a
+ *     local `function div() {}`, a `div() {}` method, a parameter, ...);
+ *   - the tag is in `STATIC_TAGS` (no table/select/pre/textarea parsing
+ *     quirks, no URL- or script-bearing elements);
+ *   - the arguments are `({...})`, `({...}, "text")`, `("text")` or
+ *     `("class", "text")`, where the object literal holds only plain or quoted
+ *     keys with string / number / `true` / `false` / `null` / `undefined`
+ *     literal values — no shorthand, spread, computed keys, methods, or
+ *     expressions of any kind;
+ *   - every attribute goes through a tag-factory path that is a plain
+ *     `setAttribute` for that value (see `attributeHtml`).
  */
 interface StaticAnalysisResult {
     /** Whether any static patterns were found */
@@ -499,14 +581,17 @@ interface StaticAnalysisResult {
     }>;
 }
 /**
- * Analyze source code for static tagFactory patterns that can be
- * converted to template cloning at build time.
+ * Analyze source code for static tag-factory calls that can be converted to
+ * template cloning at build time.
  *
- * Detects patterns like:
+ * Detects calls like:
  *   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;
 
@@ -516,35 +601,39 @@ declare function analyzeStaticTemplates(code: string): StaticAnalysisResult;
  * Transforms:
  *   html`<div class=${cls}><span>${() => count()}</span></div>`
  *
- * Into direct tagFactory calls:
- *   div({ class: __v[0], nodes: [span({ nodes: __v[1] })] })
+ * Into a module-level construction function plus a call that passes the
+ * template's expressions in their original order:
  *
- * This eliminates the runtime template parser entirely, removing the ~1.5x
- * overhead of the html`` authoring style vs direct function calls.
+ *   __sibujs$t0((cls), (() => count()))
+ *   ...
+ *   function __sibujs$t0(v0, v1) { ...direct DOM construction... }
  *
- * The runtime parser remains available as a fallback for users who don't
- * use a build step.
+ * 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 no templates found */
+    /** The transformed source code, or null if nothing was compiled */
     code: string | null;
-    /** Set of HTML tag names used (need to be imported from sibu) */
+    /** Tag names of the elements the compiled templates create */
     usedTags: Set<string>;
-    /** Whether any SVG tags were used (needs tagFactory + SVG_NS import) */
+    /** 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 all html`` tagged templates in source code to direct tagFactory calls.
- *
- * Transforms:
- *   html`<div class=${cls}><span>${text}</span></div>`
- *
- * Into:
- *   ((v) => div({ class: v[0], nodes: [span({ nodes: v[1] })] }))([cls, text])
+ * 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).
  *
- * This eliminates the runtime template parser entirely.
+ * Returns `code: null` when nothing was compiled — including when the file
+ * cannot be scanned with confidence.
  */
 declare function compileHtmlTemplates(code: string): CompileResult;
 
@@ -595,8 +684,8 @@ declare function buildRouteEntries(files: string[], chunkPrefix: string): RouteE
  * @example
  * ```ts
  * // vite.config.ts
- * import { sibuVitePlugin } from "sibu/build";
- * import { sibuRouteSplitting } from "sibu/build";
+ * import { sibuVitePlugin } from "sibujs/build";
+ * import { sibuRouteSplitting } from "sibujs/build";
  *
  * export default {
  *   plugins: [sibuVitePlugin(), sibuRouteSplitting()],
@@ -604,7 +693,7 @@ declare function buildRouteEntries(files: string[], chunkPrefix: string): RouteE
  *
  * // In your app:
  * import { routes } from "virtual:sibu-routes";
- * import { setRoutes } from "sibu/plugins";
+ * import { setRoutes } from "sibujs/plugins";
  * setRoutes(routes);
  * ```
  */

package/dist/build.d.ts

@@ -1,37 +1,76 @@
+/** 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;
-    /** Enable automatic pure annotations for tree-shaking */
+    /**
+     * 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) */
+    /**
+     * 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;
-    /** Enable static template optimization (default: true in production) */
+    /**
+     * 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 to direct function calls (default: true in production) */
+    /**
+     * Compile `html` tagged templates (imported from sibujs) to direct DOM
+     * construction. Default: true in production builds. A template the compiler
+     * cannot reproduce exactly is left to the runtime parser.
+     */
     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.
- *
- * Note: This is a configuration helper. For full Vite plugin functionality,
- * users should install @sibu/vite-plugin (when available).
  */
 declare function sibuVitePlugin(options?: SibuVitePluginOptions): {
     name: string;
     enforce?: "pre" | "post";
-    config?: () => Record<string, unknown>;
+    config?: (userConfig?: unknown, env?: ViteModeInfo) => Record<string, unknown>;
+    configResolved?: (config: ViteModeInfo) => void;
     transform?: (code: string, id: string) => {
         code: string;
-        map?: unknown;
+        map: SourceMapV3;
     } | null;
     handleHotUpdate?: (ctx: {
         file: string;
@@ -57,9 +96,21 @@ declare function createViteConfig(options?: {
  * Provides build optimization, pure annotations, and development enhancements.
  */
 interface SibuWebpackPluginOptions {
-    /** Enable automatic pure annotations for tree-shaking */
+    /**
+     * Accepted for API compatibility; the plugin itself no longer injects a
+     * loader. Webpack loaders must be resolvable modules, and 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. To get pure annotations, reference a loader file that returns
+     * `createPureAnnotationsLoader()(source)`.
+     */
     pureAnnotations?: boolean;
-    /** Enable dev mode features (devtools, debug logging) */
+    /**
+     * 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;
 }
 /**
@@ -68,7 +119,7 @@ interface SibuWebpackPluginOptions {
  *
  * Usage:
  * ```js
- * const { sibuWebpackPlugin } = require('sibu/src/build/webpack');
+ * const { sibuWebpackPlugin } = require('sibujs/build');
  * module.exports = {
  *   plugins: [sibuWebpackPlugin()],
  * };
@@ -99,7 +150,14 @@ declare function sibuWebpackPlugin(options?: SibuWebpackPluginOptions): {
 };
 /**
  * Create a standalone webpack loader function for pure annotation injection.
- * Can be used directly in webpack module rules.
+ *
+ * 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;
 /**
@@ -107,7 +165,7 @@ declare function createPureAnnotationsLoader(): (source: string) => string;
  *
  * Usage:
  * ```js
- * const { createWebpackConfig } = require('sibu/src/build/webpack');
+ * const { createWebpackConfig } = require('sibujs/build');
  * module.exports = createWebpackConfig({
  *   entry: './src/index.ts',
  *   mode: 'production',
@@ -133,7 +191,7 @@ declare function createWebpackConfig(options?: {
  *
  * Usage (in a script tag):
  * ```html
- * <script src="https://unpkg.com/sibu@latest/dist/cdn.global.js"></script>
+ * <script src="https://unpkg.com/sibujs@latest/dist/cdn.global.js"></script>
  * <script>
  *   const { div, span, mount, signal } = window.Sibu;
  *   // Use SibuJS without a bundler
@@ -180,7 +238,7 @@ declare const cdnUrls: {
      * @example
      * ```ts
      * cdnUrls.scriptTag('jsdelivr', '1.0.0')
-     * // => '<script src="https://cdn.jsdelivr.net/npm/sibu@1.0.0/dist/cdn.global.js"></script>'
+     * // => '<script src="https://cdn.jsdelivr.net/npm/sibujs@1.0.0/dist/cdn.global.js"></script>'
      * ```
      */
     scriptTag: (provider?: "unpkg" | "jsdelivr" | "skypack", version?: string) => string;
@@ -190,7 +248,7 @@ declare const cdnUrls: {
  * Useful for browser-native ES modules without a bundler.
  *
  * Import maps allow browsers to resolve bare module specifiers like
- * `import { div } from 'sibu'` without a build step.
+ * `import { div } from 'sibujs'` without a build step.
  *
  * @param baseUrl - Base URL for module resolution (defaults to jsDelivr)
  * @returns An import map object with serialization helpers
@@ -202,7 +260,7 @@ declare const cdnUrls: {
  *
  * // Now you can use bare specifiers in module scripts:
  * // <script type="module">
- * //   import { div, mount } from 'sibu';
+ * //   import { div, mount } from 'sibujs';
  * // </script>
  * ```
  */
@@ -225,7 +283,7 @@ declare function generateImportMap(baseUrl?: string): {
  *
  * @example
  * ```ts
- * import { generateTsConfig } from 'sibu/src/build/declarations';
+ * import { generateTsConfig } from 'sibujs/build';
  * import { writeFileSync } from 'fs';
  *
  * const config = generateTsConfig({ outDir: './dist' });
@@ -253,7 +311,7 @@ declare function generateTsConfig(options?: {
  *
  * @example
  * ```ts
- * import { validateTsConfig } from 'sibu/src/build/declarations';
+ * import { validateTsConfig } from 'sibujs/build';
  * import { readFileSync } from 'fs';
  *
  * const tsconfig = JSON.parse(readFileSync('tsconfig.json', 'utf-8'));
@@ -479,7 +537,31 @@ declare function generateTypeStubs(): Record<string, string>;
 
 /**
  * Static analysis utilities for SibuJS build-time optimizations.
- * Detects tagFactory calls that can be converted to template cloning.
+ * Detects tag-factory calls that can be converted to template cloning.
+ *
+ * A candidate is replaced by `staticTemplate("<markup>")`, so the analysis
+ * must PROVE that parsing the markup yields exactly the element the tag
+ * factory would have built. The earlier regex version proved nothing: it
+ * matched method calls (`db.select({...})`), text inside strings and
+ * comments, silently dropped shorthand and spread props while still calling
+ * the call static, treated `"a" + x` as a literal, and rendered `false` as
+ * `disabled="false"`. Every one of those is a production-only bug.
+ *
+ * The rule now is: optimize only what is provably equivalent, and leave
+ * everything else untouched. Concretely a call qualifies only when
+ *   - the callee is a tag factory imported from "sibujs" (by any local alias),
+ *     called directly — never `obj.tag(...)` — and the name is not declared
+ *     or used anywhere in the file in a way that could shadow the import (a
+ *     local `function div() {}`, a `div() {}` method, a parameter, ...);
+ *   - the tag is in `STATIC_TAGS` (no table/select/pre/textarea parsing
+ *     quirks, no URL- or script-bearing elements);
+ *   - the arguments are `({...})`, `({...}, "text")`, `("text")` or
+ *     `("class", "text")`, where the object literal holds only plain or quoted
+ *     keys with string / number / `true` / `false` / `null` / `undefined`
+ *     literal values — no shorthand, spread, computed keys, methods, or
+ *     expressions of any kind;
+ *   - every attribute goes through a tag-factory path that is a plain
+ *     `setAttribute` for that value (see `attributeHtml`).
  */
 interface StaticAnalysisResult {
     /** Whether any static patterns were found */
@@ -499,14 +581,17 @@ interface StaticAnalysisResult {
     }>;
 }
 /**
- * Analyze source code for static tagFactory patterns that can be
- * converted to template cloning at build time.
+ * Analyze source code for static tag-factory calls that can be converted to
+ * template cloning at build time.
  *
- * Detects patterns like:
+ * Detects calls like:
  *   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;
 
@@ -516,35 +601,39 @@ declare function analyzeStaticTemplates(code: string): StaticAnalysisResult;
  * Transforms:
  *   html`<div class=${cls}><span>${() => count()}</span></div>`
  *
- * Into direct tagFactory calls:
- *   div({ class: __v[0], nodes: [span({ nodes: __v[1] })] })
+ * Into a module-level construction function plus a call that passes the
+ * template's expressions in their original order:
  *
- * This eliminates the runtime template parser entirely, removing the ~1.5x
- * overhead of the html`` authoring style vs direct function calls.
+ *   __sibujs$t0((cls), (() => count()))
+ *   ...
+ *   function __sibujs$t0(v0, v1) { ...direct DOM construction... }
  *
- * The runtime parser remains available as a fallback for users who don't
- * use a build step.
+ * 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 no templates found */
+    /** The transformed source code, or null if nothing was compiled */
     code: string | null;
-    /** Set of HTML tag names used (need to be imported from sibu) */
+    /** Tag names of the elements the compiled templates create */
     usedTags: Set<string>;
-    /** Whether any SVG tags were used (needs tagFactory + SVG_NS import) */
+    /** 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 all html`` tagged templates in source code to direct tagFactory calls.
- *
- * Transforms:
- *   html`<div class=${cls}><span>${text}</span></div>`
- *
- * Into:
- *   ((v) => div({ class: v[0], nodes: [span({ nodes: v[1] })] }))([cls, text])
+ * 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).
  *
- * This eliminates the runtime template parser entirely.
+ * Returns `code: null` when nothing was compiled — including when the file
+ * cannot be scanned with confidence.
  */
 declare function compileHtmlTemplates(code: string): CompileResult;
 
@@ -595,8 +684,8 @@ declare function buildRouteEntries(files: string[], chunkPrefix: string): RouteE
  * @example
  * ```ts
  * // vite.config.ts
- * import { sibuVitePlugin } from "sibu/build";
- * import { sibuRouteSplitting } from "sibu/build";
+ * import { sibuVitePlugin } from "sibujs/build";
+ * import { sibuRouteSplitting } from "sibujs/build";
  *
  * export default {
  *   plugins: [sibuVitePlugin(), sibuRouteSplitting()],
@@ -604,7 +693,7 @@ declare function buildRouteEntries(files: string[], chunkPrefix: string): RouteE
  *
  * // In your app:
  * import { routes } from "virtual:sibu-routes";
- * import { setRoutes } from "sibu/plugins";
+ * import { setRoutes } from "sibujs/plugins";
  * setRoutes(routes);
  * ```
  */