@stati/core 1.23.4 → 1.24.1

package/dist/core/build.js

@@ -551,6 +551,19 @@ async function buildInternal(options = {}) {
             outDir: config.outDir || DEFAULT_OUT_DIR,
             mode: 'development',
         });
+        // On initial dev startup, watcher output may not exist yet.
+        // Compile once so pages can auto-inject bundle scripts immediately.
+        if (compiledBundles.length === 0) {
+            const endTsSpan = recorder.startSpan('typescriptCompileMs');
+            compiledBundles = await compileTypeScript({
+                projectRoot: process.cwd(),
+                config: config.typescript,
+                outDir: config.outDir || DEFAULT_OUT_DIR,
+                mode: 'development',
+                logger,
+            });
+            endTsSpan();
+        }
     }
     else if (config.typescript?.enabled) {
         const endTsSpan = recorder.startSpan('typescriptCompileMs');

package/dist/core/dev.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dev.d.ts","sourceRoot":"","sources":["../../src/core/dev.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAe,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAoC7D,MAAM,WAAW,gBAAgB;IAC/B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,SAAS;IACxB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACtB,GAAG,EAAE,MAAM,CAAC;CACb;AAybD,wBAAsB,eAAe,CAAC,OAAO,GAAE,gBAAqB,GAAG,OAAO,CAAC,SAAS,CAAC,CAqgBxF"}
+{"version":3,"file":"dev.d.ts","sourceRoot":"","sources":["../../src/core/dev.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAe,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAsC7D,MAAM,WAAW,gBAAgB;IAC/B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,SAAS;IACxB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACtB,GAAG,EAAE,MAAM,CAAC;CACb;AAscD,wBAAsB,eAAe,CAAC,OAAO,GAAE,gBAAqB,GAAG,OAAO,CAAC,SAAS,CAAC,CAihBxF"}

package/dist/core/dev.js

@@ -11,7 +11,7 @@ import { clearMarkdownProcessorCache } from './markdown.js';
 import { loadCacheManifest, saveCacheManifest, computeNavigationHash, DevServerLockManager, } from './isg/index.js';
 import { loadContent } from './content.js';
 import { buildNavigation } from './navigation.js';
-import { resolveDevPaths, resolveCacheDir, resolvePrettyUrl, createErrorOverlay, parseErrorDetails, TemplateError, createFallbackLogger, mergeServerOptions, createTypeScriptWatcher, normalizePathForComparison, isPathWithinDirectory, } from './utils/index.js';
+import { resolveDevPaths, resolveCacheDir, resolvePrettyUrl, createErrorOverlay, parseErrorDetails, TemplateError, createFallbackLogger, mergeServerOptions, createTypeScriptWatcher, isEnabledEnvFlag, refreshCssOutputWatcher, normalizePathForComparison, isPathWithinDirectory, } from './utils/index.js';
 import { setEnv, getEnv } from '../env.js';
 import { DEFAULT_DEV_PORT, DEFAULT_DEV_HOST, TEMPLATE_EXTENSION, DEFAULT_OUT_DIR, } from '../constants.js';
 /**
@@ -77,9 +77,10 @@ async function performInitialBuild(configPath, logger, onError) {
  *   active build. The `changes` Map stores file paths as keys and their event types as values,
  *   ensuring each file is only processed once with its most recent event type.
  * @param onError - Optional callback invoked when build errors occur
+ * @param onBuildEnd - Optional callback invoked after each build attempt finishes (success or failure)
  * @param batchedChanges - Array of changes to process in a single batch (used for pending queue processing)
  */
-async function performIncrementalRebuild(changedPath, eventType, configPath, staticDir, logger, wsServer, isBuildingRef, pendingChangesRef, onError, batchedChanges = []) {
+async function performIncrementalRebuild(changedPath, eventType, configPath, staticDir, logger, wsServer, isBuildingRef, pendingChangesRef, onError, onBuildEnd, batchedChanges = []) {
     // If a build is in progress, queue this change for processing after the current build
     if (isBuildingRef.value) {
         pendingChangesRef.changes.set(changedPath, eventType);
@@ -195,6 +196,14 @@ async function performIncrementalRebuild(changedPath, eventType, configPath, sta
     }
     finally {
         isBuildingRef.value = false;
+        if (onBuildEnd) {
+            try {
+                await onBuildEnd();
+            }
+            catch (error) {
+                logger.error?.(`Failed post-build hook after rebuild: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
         // Check if there are pending changes that occurred during this build
         if (pendingChangesRef.changes.size > 0) {
             // Get all pending changes - the build will process all of them at once
@@ -204,7 +213,7 @@ async function performIncrementalRebuild(changedPath, eventType, configPath, sta
             // The build() call will copy all static assets and rebuild all affected pages
             const [first, ...remaining] = pendingChanges;
             if (first) {
-                void performIncrementalRebuild(first.path, first.eventType, configPath, staticDir, logger, wsServer, isBuildingRef, pendingChangesRef, onError, remaining);
+                void performIncrementalRebuild(first.path, first.eventType, configPath, staticDir, logger, wsServer, isBuildingRef, pendingChangesRef, onError, onBuildEnd, remaining);
             }
         }
     }
@@ -405,6 +414,10 @@ export async function createDevServer(options = {}) {
     const isBuildingRef = { value: false };
     const pendingChangesRef = { changes: new Map() };
     let isStopping = false;
+    const watchedCssFiles = new Set();
+    // Diagnostics toggles used for investigating dev-server rebuild slowdown.
+    const disableCssWatcher = isEnabledEnvFlag(process.env.STATI_DEV_DISABLE_CSS_WATCHER);
+    const disableWsReload = isEnabledEnvFlag(process.env.STATI_DEV_DISABLE_WS_RELOAD);
     /**
      * Gets MIME type for a file based on its extension
      */
@@ -594,6 +607,45 @@ export async function createDevServer(options = {}) {
                 logger.error?.(`Failed to start dev server:\n${message}`);
                 throw error;
             }
+            // TypeScript watcher setup
+            // Start this before the initial build so bundle outputs already exist for auto-injection.
+            if (config.typescript?.enabled) {
+                try {
+                    // Start TypeScript watchers for hot reload (one per bundle)
+                    tsWatchers = await createTypeScriptWatcher({
+                        projectRoot: process.cwd(),
+                        config: config.typescript,
+                        outDir: config.outDir || DEFAULT_OUT_DIR,
+                        logger,
+                        awaitInitialBuild: true,
+                        onRebuild: (_results, compileTimeMs) => {
+                            logger.info?.(`▸ TypeScript recompiled in ${compileTimeMs}ms`);
+                            // Broadcast reload to WebSocket clients
+                            if (wsServer && !disableWsReload) {
+                                wsServer.clients.forEach((client) => {
+                                    const ws = client;
+                                    if (ws.readyState === 1) {
+                                        // WebSocket.OPEN
+                                        ws.send(JSON.stringify({ type: 'reload' }));
+                                    }
+                                });
+                            }
+                        },
+                    });
+                }
+                catch (error) {
+                    const tsError = error instanceof Error ? error : new Error(String(error));
+                    // Prominent notification for TypeScript setup failure
+                    console.log();
+                    logger.error?.(`TypeScript setup failed: ${tsError.message}`);
+                    logger.warning?.('──────────────────────────────────────────────────────────────');
+                    logger.warning?.('!  TypeScript hot reload is DISABLED for this session.');
+                    logger.warning?.("    Dev server will continue, but TypeScript changes won't auto-reload.");
+                    logger.warning?.('    Fix your TypeScript configuration and restart the dev server.');
+                    logger.warning?.('──────────────────────────────────────────────────────────────');
+                    console.log();
+                }
+            }
             // Perform initial build
             await performInitialBuild(configPath, logger, setLastBuildError);
             // Create HTTP server
@@ -661,43 +713,6 @@ export async function createDevServer(options = {}) {
                     reject(error);
                 });
             });
-            // TypeScript watcher setup (initial compilation is handled by performInitialBuild)
-            if (config.typescript?.enabled) {
-                try {
-                    // Start TypeScript watchers for hot reload (one per bundle)
-                    tsWatchers = await createTypeScriptWatcher({
-                        projectRoot: process.cwd(),
-                        config: config.typescript,
-                        outDir: config.outDir || DEFAULT_OUT_DIR,
-                        logger,
-                        onRebuild: (_results, compileTimeMs) => {
-                            logger.info?.(`▸ TypeScript recompiled in ${compileTimeMs}ms`);
-                            // Broadcast reload to WebSocket clients
-                            if (wsServer) {
-                                wsServer.clients.forEach((client) => {
-                                    const ws = client;
-                                    if (ws.readyState === 1) {
-                                        // WebSocket.OPEN
-                                        ws.send(JSON.stringify({ type: 'reload' }));
-                                    }
-                                });
-                            }
-                        },
-                    });
-                }
-                catch (error) {
-                    const tsError = error instanceof Error ? error : new Error(String(error));
-                    // Prominent notification for TypeScript setup failure
-                    console.log();
-                    logger.error?.(`TypeScript setup failed: ${tsError.message}`);
-                    logger.warning?.('──────────────────────────────────────────────────────────────');
-                    logger.warning?.('!  TypeScript hot reload is DISABLED for this session.');
-                    logger.warning?.("    Dev server will continue, but TypeScript changes won't auto-reload.");
-                    logger.warning?.('    Fix your TypeScript configuration and restart the dev server.');
-                    logger.warning?.('──────────────────────────────────────────────────────────────');
-                    console.log();
-                }
-            }
             // Set up file watching
             const watchPaths = [srcDir, staticDir].filter(Boolean);
             watcher = chokidar.watch(watchPaths, {
@@ -705,40 +720,42 @@ export async function createDevServer(options = {}) {
                 persistent: true,
                 ignoreInitial: true,
             });
-            // Set up separate watcher for CSS files in output directory
-            // This enables live reload when external tools (like Tailwind CLI) update CSS
-            cssWatcher = chokidar.watch([join(outDir, '**/*.css')], {
-                ignored: /(^|[/\\])\../, // ignore dotfiles
-                persistent: true,
-                ignoreInitial: true,
-            });
-            cssWatcher.on('change', (path) => {
-                const relativePath = path.replace(process.cwd(), '').replace(/\\/g, '/').replace(/^\//, '');
-                logger.info?.(`▸ ${relativePath} updated`);
-                // Just notify clients to reload - no rebuild needed since CSS was already compiled
-                if (wsServer) {
-                    wsServer.clients.forEach((client) => {
-                        const ws = client;
-                        if (ws.readyState === 1) {
-                            ws.send(JSON.stringify({ type: 'reload' }));
-                        }
-                    });
+            const refreshCssWatcher = async () => {
+                cssWatcher = await refreshCssOutputWatcher({
+                    outDir,
+                    logger,
+                    wsServer,
+                    disableWsReload,
+                    cssWatcher,
+                    watchedCssFiles,
+                });
+            };
+            if (!disableCssWatcher) {
+                await refreshCssWatcher();
+                if (!cssWatcher) {
+                    logger.info?.('  • [dev] No CSS files found in output; CSS watcher not started');
                 }
-            });
+            }
             watcher.on('change', (path) => {
-                void performIncrementalRebuild(path, 'change', configPath, staticDir, logger, wsServer, isBuildingRef, pendingChangesRef, setLastBuildError);
+                void performIncrementalRebuild(path, 'change', configPath, staticDir, logger, disableWsReload ? null : wsServer, isBuildingRef, pendingChangesRef, setLastBuildError, disableCssWatcher ? undefined : refreshCssWatcher);
             });
             watcher.on('add', (path) => {
-                void performIncrementalRebuild(path, 'add', configPath, staticDir, logger, wsServer, isBuildingRef, pendingChangesRef, setLastBuildError);
+                void performIncrementalRebuild(path, 'add', configPath, staticDir, logger, disableWsReload ? null : wsServer, isBuildingRef, pendingChangesRef, setLastBuildError, disableCssWatcher ? undefined : refreshCssWatcher);
             });
             watcher.on('unlink', (path) => {
-                void performIncrementalRebuild(path, 'unlink', configPath, staticDir, logger, wsServer, isBuildingRef, pendingChangesRef, setLastBuildError);
+                void performIncrementalRebuild(path, 'unlink', configPath, staticDir, logger, disableWsReload ? null : wsServer, isBuildingRef, pendingChangesRef, setLastBuildError, disableCssWatcher ? undefined : refreshCssWatcher);
             });
             logger.success?.(`Dev server running at ${url}`);
             logger.info?.(`\nServing:`);
             logger.info?.(`  • ${outDir}`);
             logger.info?.('Watching:');
             watchPaths.forEach((path) => logger.info?.(`  • ${path}`));
+            if (disableCssWatcher) {
+                logger.info?.('  • [diagnostic] CSS output watcher disabled');
+            }
+            if (disableWsReload) {
+                logger.info?.('  • [diagnostic] WebSocket reload broadcast disabled');
+            }
             logger.info?.('');
             // Open browser if requested
             if (open) {

package/dist/core/utils/dev-css-watcher.utils.d.ts

@@ -0,0 +1,26 @@
+import type { FSWatcher } from 'chokidar';
+import type { WebSocketServer } from 'ws';
+import type { Logger } from '../../types/index.js';
+/**
+ * Returns concrete CSS files currently present in outDir.
+ *
+ * Watching explicit files avoids a broad recursive outDir glob watcher,
+ * which can add significant overhead on large docs sites.
+ */
+export declare function discoverOutputCssFiles(outDir: string): Promise<string[]>;
+export interface RefreshCssOutputWatcherParams {
+    outDir: string;
+    logger: Logger;
+    wsServer: WebSocketServer | null;
+    disableWsReload: boolean;
+    cssWatcher: FSWatcher | null;
+    watchedCssFiles: Set<string>;
+}
+/**
+ * Reconciles the CSS watcher with the current output CSS file membership.
+ *
+ * If the file set changed, this closes the previous watcher and creates a new one
+ * bound to the latest concrete files.
+ */
+export declare function refreshCssOutputWatcher(params: RefreshCssOutputWatcherParams): Promise<FSWatcher | null>;
+//# sourceMappingURL=dev-css-watcher.utils.d.ts.map

package/dist/core/utils/dev-css-watcher.utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dev-css-watcher.utils.d.ts","sourceRoot":"","sources":["../../../src/core/utils/dev-css-watcher.utils.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAC1C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,IAAI,CAAC;AAC1C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAC;AAGnD;;;;;GAKG;AACH,wBAAsB,sBAAsB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAa9E;AA0BD,MAAM,WAAW,6BAA6B;IAC5C,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,eAAe,GAAG,IAAI,CAAC;IACjC,eAAe,EAAE,OAAO,CAAC;IACzB,UAAU,EAAE,SAAS,GAAG,IAAI,CAAC;IAC7B,eAAe,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;CAC9B;AAED;;;;;GAKG;AACH,wBAAsB,uBAAuB,CAC3C,MAAM,EAAE,6BAA6B,GACpC,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC,CAgC3B"}

package/dist/core/utils/dev-css-watcher.utils.js

@@ -0,0 +1,70 @@
+import chokidar from 'chokidar';
+import fg from 'fast-glob';
+import { pathExists } from './fs.utils.js';
+/**
+ * Returns concrete CSS files currently present in outDir.
+ *
+ * Watching explicit files avoids a broad recursive outDir glob watcher,
+ * which can add significant overhead on large docs sites.
+ */
+export async function discoverOutputCssFiles(outDir) {
+    if (!(await pathExists(outDir))) {
+        return [];
+    }
+    const cssFiles = await fg('**/*.css', {
+        cwd: outDir,
+        absolute: true,
+        onlyFiles: true,
+        dot: false,
+    });
+    return cssFiles;
+}
+function hasSameMembership(nextFiles, watchedCssFiles) {
+    if (nextFiles.length !== watchedCssFiles.size) {
+        return false;
+    }
+    return nextFiles.every((file) => watchedCssFiles.has(file));
+}
+function broadcastReload(wsServer, disableWsReload, payload) {
+    if (!wsServer || disableWsReload) {
+        return;
+    }
+    wsServer.clients.forEach((client) => {
+        const ws = client;
+        if (ws.readyState === 1) {
+            ws.send(payload);
+        }
+    });
+}
+/**
+ * Reconciles the CSS watcher with the current output CSS file membership.
+ *
+ * If the file set changed, this closes the previous watcher and creates a new one
+ * bound to the latest concrete files.
+ */
+export async function refreshCssOutputWatcher(params) {
+    const { outDir, logger, wsServer, disableWsReload, cssWatcher, watchedCssFiles } = params;
+    const cssFiles = await discoverOutputCssFiles(outDir);
+    if (hasSameMembership(cssFiles, watchedCssFiles)) {
+        return cssWatcher;
+    }
+    if (cssWatcher) {
+        await cssWatcher.close();
+    }
+    watchedCssFiles.clear();
+    cssFiles.forEach((file) => watchedCssFiles.add(file));
+    if (cssFiles.length === 0) {
+        return null;
+    }
+    const nextCssWatcher = chokidar.watch(cssFiles, {
+        ignored: /(^|[/\\])\../,
+        persistent: true,
+        ignoreInitial: true,
+    });
+    nextCssWatcher.on('change', (path) => {
+        const relativePath = path.replace(process.cwd(), '').replace(/\\/g, '/').replace(/^\//, '');
+        logger.info?.(`▸ ${relativePath} updated`);
+        broadcastReload(wsServer, disableWsReload, JSON.stringify({ type: 'reload' }));
+    });
+    return nextCssWatcher;
+}

package/dist/core/utils/env.utils.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Parses common truthy environment flag values.
+ */
+export declare function isEnabledEnvFlag(value: string | undefined): boolean;
+//# sourceMappingURL=env.utils.d.ts.map

package/dist/core/utils/env.utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.utils.d.ts","sourceRoot":"","sources":["../../../src/core/utils/env.utils.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAGnE"}

package/dist/core/utils/env.utils.js

@@ -0,0 +1,8 @@
+/**
+ * Parses common truthy environment flag values.
+ */
+export function isEnabledEnvFlag(value) {
+    if (!value)
+        return false;
+    return ['1', 'true', 'yes', 'on'].includes(value.toLowerCase());
+}

package/dist/core/utils/index.d.ts

@@ -25,4 +25,7 @@ export { createFallbackLogger } from './logger.utils.js';
 export { compileTypeScript, createTypeScriptWatcher, compileStatiConfig, cleanupCompiledConfig, autoInjectBundles, formatBytes, detectExistingBundles, } from './typescript.utils.js';
 export type { CompileOptions, WatchOptions } from './typescript.utils.js';
 export { findHeadClosePosition, injectBeforeHeadClose } from './html.utils.js';
+export { isEnabledEnvFlag } from './env.utils.js';
+export { discoverOutputCssFiles, refreshCssOutputWatcher } from './dev-css-watcher.utils.js';
+export type { RefreshCssOutputWatcherParams } from './dev-css-watcher.utils.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/core/utils/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/core/utils/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EACL,QAAQ,EACR,SAAS,EACT,UAAU,EACV,SAAS,EACT,MAAM,EACN,QAAQ,EACR,OAAO,EACP,IAAI,GACL,MAAM,eAAe,CAAC;AAGvB,OAAO,EACL,aAAa,EACb,aAAa,EACb,gBAAgB,EAChB,eAAe,EACf,eAAe,EACf,qBAAqB,EACrB,cAAc,EACd,cAAc,EACd,iBAAiB,EACjB,0BAA0B,EAC1B,qBAAqB,GACtB,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EACL,cAAc,EACd,qBAAqB,EACrB,wBAAwB,GACzB,MAAM,+BAA+B,CAAC;AAGvC,OAAO,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAGhD,OAAO,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAG7C,OAAO,EACL,kBAAkB,EAClB,uBAAuB,EACvB,wBAAwB,EACxB,cAAc,EACd,YAAY,EACZ,gBAAgB,EAChB,iBAAiB,EACjB,2BAA2B,EAC3B,cAAc,EACd,sBAAsB,EACtB,qBAAqB,GACtB,MAAM,+BAA+B,CAAC;AAGvC,OAAO,EAAE,6BAA6B,EAAE,MAAM,+BAA+B,CAAC;AAG9E,OAAO,EAAE,mBAAmB,EAAE,sBAAsB,EAAE,MAAM,8BAA8B,CAAC;AAC3F,YAAY,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAGpE,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAG/F,OAAO,EAAE,uBAAuB,EAAE,MAAM,+BAA+B,CAAC;AAGxE,OAAO,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AACzE,YAAY,EACV,eAAe,EACf,mBAAmB,EACnB,wBAAwB,GACzB,MAAM,mBAAmB,CAAC;AAG3B,OAAO,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AACjF,YAAY,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAG7D,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAGrD,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAGpE,OAAO,EACL,mBAAmB,EACnB,qBAAqB,EACrB,yBAAyB,EACzB,wBAAwB,GACzB,MAAM,4BAA4B,CAAC;AACpC,YAAY,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AAGrE,OAAO,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AAGzD,OAAO,EACL,iBAAiB,EACjB,uBAAuB,EACvB,kBAAkB,EAClB,qBAAqB,EACrB,iBAAiB,EACjB,WAAW,EACX,qBAAqB,GACtB,MAAM,uBAAuB,CAAC;AAC/B,YAAY,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAG1E,OAAO,EAAE,qBAAqB,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/core/utils/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EACL,QAAQ,EACR,SAAS,EACT,UAAU,EACV,SAAS,EACT,MAAM,EACN,QAAQ,EACR,OAAO,EACP,IAAI,GACL,MAAM,eAAe,CAAC;AAGvB,OAAO,EACL,aAAa,EACb,aAAa,EACb,gBAAgB,EAChB,eAAe,EACf,eAAe,EACf,qBAAqB,EACrB,cAAc,EACd,cAAc,EACd,iBAAiB,EACjB,0BAA0B,EAC1B,qBAAqB,GACtB,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EACL,cAAc,EACd,qBAAqB,EACrB,wBAAwB,GACzB,MAAM,+BAA+B,CAAC;AAGvC,OAAO,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAGhD,OAAO,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAG7C,OAAO,EACL,kBAAkB,EAClB,uBAAuB,EACvB,wBAAwB,EACxB,cAAc,EACd,YAAY,EACZ,gBAAgB,EAChB,iBAAiB,EACjB,2BAA2B,EAC3B,cAAc,EACd,sBAAsB,EACtB,qBAAqB,GACtB,MAAM,+BAA+B,CAAC;AAGvC,OAAO,EAAE,6BAA6B,EAAE,MAAM,+BAA+B,CAAC;AAG9E,OAAO,EAAE,mBAAmB,EAAE,sBAAsB,EAAE,MAAM,8BAA8B,CAAC;AAC3F,YAAY,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAGpE,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAG/F,OAAO,EAAE,uBAAuB,EAAE,MAAM,+BAA+B,CAAC;AAGxE,OAAO,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AACzE,YAAY,EACV,eAAe,EACf,mBAAmB,EACnB,wBAAwB,GACzB,MAAM,mBAAmB,CAAC;AAG3B,OAAO,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AACjF,YAAY,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAG7D,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAGrD,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAGpE,OAAO,EACL,mBAAmB,EACnB,qBAAqB,EACrB,yBAAyB,EACzB,wBAAwB,GACzB,MAAM,4BAA4B,CAAC;AACpC,YAAY,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AAGrE,OAAO,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AAGzD,OAAO,EACL,iBAAiB,EACjB,uBAAuB,EACvB,kBAAkB,EAClB,qBAAqB,EACrB,iBAAiB,EACjB,WAAW,EACX,qBAAqB,GACtB,MAAM,uBAAuB,CAAC;AAC/B,YAAY,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAG1E,OAAO,EAAE,qBAAqB,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAG/E,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAGlD,OAAO,EAAE,sBAAsB,EAAE,uBAAuB,EAAE,MAAM,4BAA4B,CAAC;AAC7F,YAAY,EAAE,6BAA6B,EAAE,MAAM,4BAA4B,CAAC"}

package/dist/core/utils/index.js

@@ -38,3 +38,7 @@ export { createFallbackLogger } from './logger.utils.js';
 export { compileTypeScript, createTypeScriptWatcher, compileStatiConfig, cleanupCompiledConfig, autoInjectBundles, formatBytes, detectExistingBundles, } from './typescript.utils.js';
 // HTML manipulation utilities
 export { findHeadClosePosition, injectBeforeHeadClose } from './html.utils.js';
+// Environment utilities
+export { isEnabledEnvFlag } from './env.utils.js';
+// Dev-server CSS watcher utilities
+export { discoverOutputCssFiles, refreshCssOutputWatcher } from './dev-css-watcher.utils.js';

package/dist/core/utils/typescript.utils.d.ts

@@ -42,6 +42,11 @@ export interface WatchOptions {
     logger: Logger;
     /** Callback invoked when files are recompiled, receives results and compile time in ms */
     onRebuild: (results: CompiledBundleInfo[], compileTimeMs: number) => void;
+    /**
+     * Whether to wait for the initial watch build to finish for all bundles.
+     * Useful during dev-server startup to ensure bundle files exist before page rendering.
+     */
+    awaitInitialBuild?: boolean;
 }
 /**
  * Detects existing TypeScript bundles in the output directory.

package/dist/core/utils/typescript.utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"typescript.utils.d.ts","sourceRoot":"","sources":["../../../src/core/utils/typescript.utils.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,OAAO,MAAM,SAAS,CAAC;AAInC,OAAO,EAA6B,KAAK,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AAChG,OAAO,KAAK,EAAE,gBAAgB,EAAgB,MAAM,uBAAuB,CAAC;AAC5E,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAC;AAQrD;;GAEG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAQjD;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,oCAAoC;IACpC,WAAW,EAAE,MAAM,CAAC;IACpB,+BAA+B;IAC/B,MAAM,EAAE,gBAAgB,CAAC;IACzB,4CAA4C;IAC5C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,uBAAuB;IACvB,IAAI,EAAE,aAAa,GAAG,YAAY,CAAC;IACnC,iCAAiC;IACjC,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,oCAAoC;IACpC,WAAW,EAAE,MAAM,CAAC;IACpB,+BAA+B;IAC/B,MAAM,EAAE,gBAAgB,CAAC;IACzB,4CAA4C;IAC5C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,iCAAiC;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,0FAA0F;IAC1F,SAAS,EAAE,CAAC,OAAO,EAAE,kBAAkB,EAAE,EAAE,aAAa,EAAE,MAAM,KAAK,IAAI,CAAC;CAC3E;AAuCD;;;;;;;GAOG;AACH,wBAAsB,qBAAqB,CACzC,OAAO,EAAE,IAAI,CAAC,cAAc,EAAE,QAAQ,CAAC,GACtC,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAyC/B;AAuED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAsB,iBAAiB,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAkD9F;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,uBAAuB,CAC3C,OAAO,EAAE,YAAY,GACpB,OAAO,CAAC,OAAO,CAAC,YAAY,EAAE,CAAC,CAkGjC;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,kBAAkB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAgB5E;AAED;;;;GAIG;AACH,wBAAsB,qBAAqB,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAM/E;AAED;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAqC7D;AAiBD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,GAAG,MAAM,CA8B7E"}
+{"version":3,"file":"typescript.utils.d.ts","sourceRoot":"","sources":["../../../src/core/utils/typescript.utils.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,OAAO,MAAM,SAAS,CAAC;AAInC,OAAO,EAA6B,KAAK,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AAChG,OAAO,KAAK,EAAE,gBAAgB,EAAgB,MAAM,uBAAuB,CAAC;AAC5E,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAC;AAQrD;;GAEG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAQjD;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,oCAAoC;IACpC,WAAW,EAAE,MAAM,CAAC;IACpB,+BAA+B;IAC/B,MAAM,EAAE,gBAAgB,CAAC;IACzB,4CAA4C;IAC5C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,uBAAuB;IACvB,IAAI,EAAE,aAAa,GAAG,YAAY,CAAC;IACnC,iCAAiC;IACjC,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,oCAAoC;IACpC,WAAW,EAAE,MAAM,CAAC;IACpB,+BAA+B;IAC/B,MAAM,EAAE,gBAAgB,CAAC;IACzB,4CAA4C;IAC5C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,iCAAiC;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,0FAA0F;IAC1F,SAAS,EAAE,CAAC,OAAO,EAAE,kBAAkB,EAAE,EAAE,aAAa,EAAE,MAAM,KAAK,IAAI,CAAC;IAC1E;;;OAGG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B;AAuCD;;;;;;;GAOG;AACH,wBAAsB,qBAAqB,CACzC,OAAO,EAAE,IAAI,CAAC,cAAc,EAAE,QAAQ,CAAC,GACtC,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAyC/B;AAuED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAsB,iBAAiB,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAkD9F;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,uBAAuB,CAC3C,OAAO,EAAE,YAAY,GACpB,OAAO,CAAC,OAAO,CAAC,YAAY,EAAE,CAAC,CAyHjC;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,kBAAkB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAgB5E;AAED;;;;GAIG;AACH,wBAAsB,qBAAqB,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAM/E;AAED;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAqC7D;AAiBD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,GAAG,MAAM,CA8B7E"}

package/dist/core/utils/typescript.utils.js

@@ -217,12 +217,13 @@ export async function compileTypeScript(options) {
  * ```
  */
 export async function createTypeScriptWatcher(options) {
-    const { projectRoot, config, logger, onRebuild, outDir: globalOutDir } = options;
+    const { projectRoot, config, logger, onRebuild, outDir: globalOutDir, awaitInitialBuild = false, } = options;
     const resolved = resolveConfig(config, 'development');
     const outputDir = globalOutDir || DEFAULT_OUT_DIR;
     const outDir = path.join(projectRoot, outputDir, resolved.outDir);
     const contexts = [];
     const latestResults = new Map();
+    const initialBuildPromises = [];
     for (const bundleConfig of resolved.bundles) {
         const entryPath = path.join(projectRoot, resolved.srcDir, bundleConfig.entryPoint);
         // Validate entry point exists
@@ -230,10 +231,14 @@ export async function createTypeScriptWatcher(options) {
             logger.warning(`TypeScript entry point not found: ${entryPath} (bundle: ${bundleConfig.bundleName})`);
             continue;
         }
-        // Track whether this is the initial build triggered by context.watch()
-        // We skip notifications for the initial build since files were just compiled
-        // by compileTypeScript() during the initial build phase
+        // Track whether this is the initial build triggered by context.watch().
+        // We skip reload notifications for this build to avoid a reload storm during startup.
         let isInitialBuild = true;
+        let resolveInitialBuild;
+        const initialBuildPromise = new Promise((resolve) => {
+            resolveInitialBuild = resolve;
+        });
+        initialBuildPromises.push(initialBuildPromise);
         const context = await esbuild.context({
             entryPoints: [entryPath],
             bundle: true,
@@ -275,15 +280,21 @@ export async function createTypeScriptWatcher(options) {
                                     path: bundlePath,
                                 };
                                 latestResults.set(bundleConfig.bundleName, bundleResult);
-                                // Skip notifications for the initial build triggered by context.watch()
-                                // since files were already compiled during performInitialBuild()
+                                // Skip notifications for the initial build triggered by context.watch().
+                                // This avoids triggering a reload while startup priming is still in progress.
                                 if (isInitialBuild) {
                                     isInitialBuild = false;
+                                    resolveInitialBuild();
                                     return;
                                 }
                                 logger.info(`TypeScript '${bundleConfig.bundleName}' recompiled.`);
                                 // Notify with all current results and compile time
                                 onRebuild(Array.from(latestResults.values()), compileTime);
+                                return;
+                            }
+                            if (isInitialBuild) {
+                                isInitialBuild = false;
+                                resolveInitialBuild();
                             }
                         });
                     },
@@ -294,6 +305,9 @@ export async function createTypeScriptWatcher(options) {
         await context.watch();
         contexts.push(context);
     }
+    if (awaitInitialBuild && initialBuildPromises.length > 0) {
+        await Promise.all(initialBuildPromises);
+    }
     if (contexts.length > 0) {
         logger.info(`Watching TypeScript files in ${resolved.srcDir}/ (${contexts.length} bundle${contexts.length > 1 ? 's' : ''})`);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stati/core",
-  "version": "1.23.4",
+  "version": "1.24.1",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",