handoff-app 1.0.6 → 1.1.0-0

package/Changelog.md

@@ -6,6 +6,66 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to
 [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## \[1.1.0] - 2026-03-05
+
+This release introduces two major new features. First, handoff now can do automatic
+type detection in typescript files. By using a new library we wrote to leverage the
+typescript engine, we can automatically extract types from your components and give
+you visiblity into the type architecture across your whole project.
+
+Second, we've long wanted to support the Storybook component story format, and this
+release provides robust support for stories expressed as tsx or js files.
+
+This release also does significant cleanup and quality of life improvements. We've
+fixed some longstanding annoyances, and continue to focus the application.
+
+### Automatic type documentation
+
+* Integrated **handoff-docgen** for component documentation: props and types are
+  inferred from React/TSX components and merged with story data where available.
+* Properties table shows inferred types, default values, and descriptions from
+  component source and story argTypes.
+* Empty state message when no properties are documented; improved layout and
+  formatting for inline and default values in the Preview component.
+
+### CSF support
+
+* Components can use Storybook-style Component Story Format (`.stories.tsx` / `.stories.js`).
+  Stories are parsed to generate variants, args, and argTypes for the component page.
+* CSF parsing supports deep type nesting and correctly shows nested items for both
+  Handlebars and CSF components.
+* New example component `example-csf` demonstrates CSF integration alongside the
+  existing Handlebars and React examples.
+
+### Component page and code display
+
+* **Handlebars formatting:** Code highlight now supports Handlebars (`.hbs`) templates—
+  syntax highlighting uses the correct language instead of plain HTML.
+* Handlebars components no longer show rendered HTML in the Code snippet dropdown;
+  the template source is shown correctly.
+* Empty code tabs are filtered from the dropdown; HTML fallback for inactive states
+  removed for clearer code view.
+* Preview dropdown shows the active variant instead of a placeholder; style loading
+  and incremental component summary updates fixed in watch mode.
+* Prev/next navigation respects component group boundaries and hides invalid links.
+
+### Cleanup and internal changes
+
+* Removed legacy integration directory and relocated component scaffolding templates
+  under `integration/components/` (e.g. `example`, `example-csf`, `example-react`).
+* Removed legacy shared styles pipeline; `makeComponent` and config now use
+  `config.entries.components` consistently.
+* Removed deprecated `serverRuntimeConfig` usage, outdated `.env.example` with
+  incorrect variable names, and the patch-package workaround where no longer needed.
+* Dependencies cleanup and package updates.
+* Internal reorg: new `app-builder` (build, watchers, client config, websocket),
+  pipeline split into `pipeline/` (archive, components, figma, styles, validation),
+  config split into `config/` (defaults, loader, runtime, validator), and READMEs
+  added for major modules.
+* Global CSS/JS bundles now build on startup in dev mode; watcher added to rebuild
+  main bundles and components when global entry files change.
+* Stale JSDoc and command descriptions updated.
+
 ## \[1.0.6] - 2026-02-24
 
 Version 1.0.4 fixed an issue when running Handoff in subpaths (eg.

package/config/config.template.js

@@ -55,8 +55,7 @@ module.exports = {
   entries: {
     scss: './sass/main.scss',
     js: './js/main.js',
-    bundle: './js/main.js',
-    components: ['./integration/components'],
+    components: ['./components'],
   },
   // These are the asset zip file download links
   assets_zip_links: {

package/dist/{app.d.ts → app-builder/build.d.ts}

@@ -1,22 +1,16 @@
-import Handoff from '.';
+import Handoff from '..';
 /**
- * Build the next js application
- * @param handoff
- * @returns
+ * Build the Next.js documentation application.
  */
 declare const buildApp: (handoff: Handoff, skipComponents?: boolean) => Promise<void>;
 /**
- * Watch the next js application.
+ * Watch the Next.js application.
  * Starts a custom dev server with Handoff-specific watchers and hot-reloading.
- *
- * @param handoff
  */
 export declare const watchApp: (handoff: Handoff) => Promise<void>;
 /**
- * Watch the next js application using the standard Next.js dev server.
+ * Watch the Next.js application using the standard Next.js dev server.
  * This is useful for debugging the Next.js app itself without the Handoff overlay.
- *
- * @param handoff
  */
 export declare const devApp: (handoff: Handoff) => Promise<void>;
 export default buildApp;

package/dist/app-builder/build.js

@@ -0,0 +1,207 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.devApp = exports.watchApp = void 0;
+const cross_spawn_1 = __importDefault(require("cross-spawn"));
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const path_1 = __importDefault(require("path"));
+const components_1 = require("../pipeline/components");
+const css_1 = require("../transformers/preview/component/css");
+const javascript_1 = require("../transformers/preview/component/javascript");
+const builder_1 = __importDefault(require("../transformers/preview/component/builder"));
+const logger_1 = require("../utils/logger");
+const client_config_1 = require("./client-config");
+const paths_1 = require("./paths");
+const watchers_1 = require("./watchers");
+const websocket_1 = require("./websocket");
+/**
+ * Performs cleanup of the application directory by removing the existing app directory if it exists.
+ */
+const cleanupAppDirectory = (handoff) => __awaiter(void 0, void 0, void 0, function* () {
+    const appPath = (0, paths_1.getAppPath)(handoff);
+    // Clean project app dir
+    if (fs_extra_1.default.existsSync(appPath)) {
+        yield fs_extra_1.default.remove(appPath);
+    }
+});
+/**
+ * Prepares the project application by copying source files and configuring Next.js.
+ *
+ * @returns The path to the prepared application directory
+ */
+const initializeProjectApp = (handoff) => __awaiter(void 0, void 0, void 0, function* () {
+    var _a, _b, _c;
+    const srcPath = path_1.default.resolve(handoff.modulePath, 'src', 'app');
+    const appPath = (0, paths_1.getAppPath)(handoff);
+    // Publish tokens API
+    yield (0, client_config_1.generateTokensApi)(handoff);
+    // Prepare project app dir
+    yield fs_extra_1.default.ensureDir(appPath);
+    yield fs_extra_1.default.copy(srcPath, appPath, { overwrite: true, filter: (file) => !file.includes('next.config.mjs') });
+    yield (0, paths_1.syncPublicFiles)(handoff);
+    // Copy custom theme CSS if it exists in the user's project
+    const customThemePath = path_1.default.resolve(handoff.workingPath, 'theme.css');
+    if (fs_extra_1.default.existsSync(customThemePath)) {
+        const destPath = path_1.default.resolve(appPath, 'css', 'theme.css');
+        yield fs_extra_1.default.copy(customThemePath, destPath, { overwrite: true });
+        logger_1.Logger.success(`Custom theme.css loaded`);
+    }
+    // Prepare project app configuration
+    // Warning: Regex replacement is fragile and depends on exact formatting in next.config.mjs
+    const handoffProjectId = handoff.getProjectId();
+    const handoffAppBasePath = (_a = handoff.config.app.base_path) !== null && _a !== void 0 ? _a : '';
+    const handoffWorkingPath = path_1.default.resolve(handoff.workingPath);
+    const handoffModulePath = path_1.default.resolve(handoff.modulePath);
+    const handoffExportPath = path_1.default.resolve(handoff.workingPath, handoff.exportsDirectory, handoff.getProjectId());
+    const nextConfigPath = path_1.default.resolve(srcPath, 'next.config.mjs');
+    const targetPath = path_1.default.resolve(appPath, 'next.config.mjs');
+    const handoffWebsocketPort = (_c = (_b = handoff.config.app.ports) === null || _b === void 0 ? void 0 : _b.websocket) !== null && _c !== void 0 ? _c : 3001;
+    const nextConfigContent = (yield fs_extra_1.default.readFile(nextConfigPath, 'utf-8'))
+        .replace(/basePath:\s+''/g, `basePath: '${handoffAppBasePath}'`)
+        .replace(/HANDOFF_PROJECT_ID:\s+''/g, `HANDOFF_PROJECT_ID: '${handoffProjectId}'`)
+        .replace(/HANDOFF_APP_BASE_PATH:\s+''/g, `HANDOFF_APP_BASE_PATH: '${handoffAppBasePath}'`)
+        .replace(/HANDOFF_WORKING_PATH:\s+''/g, `HANDOFF_WORKING_PATH: '${handoffWorkingPath}'`)
+        .replace(/HANDOFF_MODULE_PATH:\s+''/g, `HANDOFF_MODULE_PATH: '${handoffModulePath}'`)
+        .replace(/HANDOFF_EXPORT_PATH:\s+''/g, `HANDOFF_EXPORT_PATH: '${handoffExportPath}'`)
+        .replace(/HANDOFF_WEBSOCKET_PORT:\s+''/g, `HANDOFF_WEBSOCKET_PORT: '${handoffWebsocketPort}'`)
+        .replace(/%HANDOFF_MODULE_PATH%/g, handoffModulePath);
+    yield fs_extra_1.default.writeFile(targetPath, nextConfigContent);
+    return appPath;
+});
+/**
+ * Build the Next.js documentation application.
+ */
+const buildApp = (handoff, skipComponents) => __awaiter(void 0, void 0, void 0, function* () {
+    skipComponents = skipComponents !== null && skipComponents !== void 0 ? skipComponents : false;
+    // Perform cleanup
+    yield cleanupAppDirectory(handoff);
+    // Build components
+    if (!skipComponents) {
+        yield (0, components_1.buildComponents)(handoff);
+    }
+    // Prepare app
+    const appPath = yield initializeProjectApp(handoff);
+    yield (0, client_config_1.persistClientConfig)(handoff);
+    // Build app
+    const buildResult = cross_spawn_1.default.sync('npx', ['next', 'build'], {
+        cwd: appPath,
+        stdio: 'inherit',
+        env: Object.assign(Object.assign({}, process.env), { NODE_ENV: 'production' }),
+    });
+    if (buildResult.status !== 0) {
+        let errorMsg = `Next.js build failed with exit code ${buildResult.status}`;
+        if (buildResult.error) {
+            errorMsg += `\nSpawn error: ${buildResult.error.message}`;
+        }
+        throw new Error(errorMsg);
+    }
+    // Ensure output root directory exists
+    const outputRoot = path_1.default.resolve(handoff.workingPath, handoff.sitesDirectory);
+    yield fs_extra_1.default.ensureDir(outputRoot);
+    // Clean the project output directory (if exists)
+    const output = path_1.default.resolve(outputRoot, handoff.getProjectId());
+    if (fs_extra_1.default.existsSync(output)) {
+        yield fs_extra_1.default.remove(output);
+    }
+    // Copy the build files into the project output directory
+    yield fs_extra_1.default.copy(path_1.default.resolve(appPath, 'out'), output);
+});
+/**
+ * Watch the Next.js application.
+ * Starts a custom dev server with Handoff-specific watchers and hot-reloading.
+ */
+const watchApp = (handoff) => __awaiter(void 0, void 0, void 0, function* () {
+    var _a, _b, _c, _d;
+    // Initial processing of the components with caching enabled
+    // This will skip rebuilding components whose source files haven't changed
+    yield (0, builder_1.default)(handoff, undefined, undefined, { useCache: true });
+    yield (0, javascript_1.buildMainJS)(handoff);
+    yield (0, css_1.buildMainCss)(handoff);
+    const appPath = yield initializeProjectApp(handoff);
+    // Persist client configuration
+    yield (0, client_config_1.persistClientConfig)(handoff);
+    // Watch app source
+    (0, watchers_1.watchAppSource)(handoff, initializeProjectApp);
+    const hostname = 'localhost';
+    const port = (_b = (_a = handoff.config.app.ports) === null || _a === void 0 ? void 0 : _a.app) !== null && _b !== void 0 ? _b : 3000;
+    // purge out cache
+    const moduleOutput = path_1.default.resolve(appPath, 'out');
+    if (fs_extra_1.default.existsSync(moduleOutput)) {
+        yield fs_extra_1.default.remove(moduleOutput);
+        // create empty directory
+        yield fs_extra_1.default.ensureDir(moduleOutput);
+    }
+    const nextProcess = (0, cross_spawn_1.default)('npx', ['next', 'dev', '--turbopack', '--port', String(port)], {
+        cwd: appPath,
+        stdio: 'inherit',
+        env: Object.assign(Object.assign({}, process.env), { NODE_ENV: 'development' }),
+    });
+    logger_1.Logger.success(`Ready on http://${hostname}:${port}`);
+    nextProcess.on('error', (error) => {
+        logger_1.Logger.error(`Next.js dev process error: ${error}`);
+        process.exit(1);
+    });
+    nextProcess.on('close', (code) => {
+        logger_1.Logger.success(`Next.js dev process closed with code ${code}`);
+        process.exit(code);
+    });
+    const wss = yield (0, websocket_1.createWebSocketServer)((_d = (_c = handoff.config.app.ports) === null || _c === void 0 ? void 0 : _c.websocket) !== null && _d !== void 0 ? _d : 3001);
+    const chokidarConfig = {
+        ignored: /(^|[\/\\])\../, // ignore dotfiles
+        persistent: true,
+        ignoreInitial: true,
+    };
+    const state = {
+        debounce: false,
+        runtimeComponentsWatcher: null,
+        runtimeConfigurationWatcher: null,
+    };
+    (0, watchers_1.watchPublicDirectory)(handoff, wss, state, chokidarConfig);
+    (0, watchers_1.watchRuntimeComponents)(handoff, state, (0, watchers_1.getRuntimeComponentsPathsToWatch)(handoff));
+    (0, watchers_1.watchRuntimeConfiguration)(handoff, state);
+    (0, watchers_1.watchGlobalEntries)(handoff, state, chokidarConfig);
+    (0, watchers_1.watchPages)(handoff, chokidarConfig);
+});
+exports.watchApp = watchApp;
+/**
+ * Watch the Next.js application using the standard Next.js dev server.
+ * This is useful for debugging the Next.js app itself without the Handoff overlay.
+ */
+const devApp = (handoff) => __awaiter(void 0, void 0, void 0, function* () {
+    var _a, _b;
+    // Prepare app
+    const appPath = yield initializeProjectApp(handoff);
+    // Purge app cache
+    const moduleOutput = path_1.default.resolve(appPath, 'out');
+    if (fs_extra_1.default.existsSync(moduleOutput)) {
+        yield fs_extra_1.default.remove(moduleOutput);
+    }
+    // Persist client configuration
+    yield (0, client_config_1.persistClientConfig)(handoff);
+    // Run
+    const devResult = cross_spawn_1.default.sync('npx', ['next', 'dev', '--turbopack', '--port', String((_b = (_a = handoff.config.app.ports) === null || _a === void 0 ? void 0 : _a.app) !== null && _b !== void 0 ? _b : 3000)], {
+        cwd: appPath,
+        stdio: 'inherit',
+        env: Object.assign(Object.assign({}, process.env), { NODE_ENV: 'development' }),
+    });
+    if (devResult.status !== 0) {
+        let errorMsg = `Next.js dev failed with exit code ${devResult.status}`;
+        if (devResult.error) {
+            errorMsg += `\nSpawn error: ${devResult.error.message}`;
+        }
+        throw new Error(errorMsg);
+    }
+});
+exports.devApp = devApp;
+exports.default = buildApp;

package/dist/app-builder/client-config.d.ts

@@ -0,0 +1,9 @@
+import Handoff from '..';
+/**
+ * Publishes the tokens API files to the public directory.
+ */
+export declare const generateTokensApi: (handoff: Handoff) => Promise<void>;
+/**
+ * Persists the client config to a JSON file.
+ */
+export declare const persistClientConfig: (handoff: Handoff) => Promise<void>;

package/dist/app-builder/client-config.js

@@ -0,0 +1,62 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.persistClientConfig = exports.generateTokensApi = void 0;
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const path_1 = __importDefault(require("path"));
+const config_1 = require("../config");
+const paths_1 = require("./paths");
+/**
+ * Publishes the tokens API files to the public directory.
+ */
+const generateTokensApi = (handoff) => __awaiter(void 0, void 0, void 0, function* () {
+    const apiPath = path_1.default.resolve(path_1.default.join(handoff.workingPath, 'public/api'));
+    yield fs_extra_1.default.ensureDir(apiPath);
+    const tokens = yield handoff.getDocumentationObject();
+    // Early return if no tokens
+    if (!tokens) {
+        // Write empty tokens.json for API consistency
+        yield fs_extra_1.default.writeJson(path_1.default.join(apiPath, 'tokens.json'), {}, { spaces: 2 });
+        return;
+    }
+    yield fs_extra_1.default.writeJson(path_1.default.join(apiPath, 'tokens.json'), tokens, { spaces: 2 });
+    const tokensDir = path_1.default.join(apiPath, 'tokens');
+    yield fs_extra_1.default.ensureDir(tokensDir);
+    // Only iterate if tokens has properties
+    if (tokens && typeof tokens === 'object') {
+        const promises = [];
+        for (const type in tokens) {
+            if (type === 'timestamp' || !tokens[type] || typeof tokens[type] !== 'object')
+                continue;
+            for (const group in tokens[type]) {
+                if (tokens[type][group]) {
+                    promises.push(fs_extra_1.default.writeJson(path_1.default.join(tokensDir, `${group}.json`), tokens[type][group], { spaces: 2 }));
+                }
+            }
+        }
+        yield Promise.all(promises);
+    }
+});
+exports.generateTokensApi = generateTokensApi;
+/**
+ * Persists the client config to a JSON file.
+ */
+const persistClientConfig = (handoff) => __awaiter(void 0, void 0, void 0, function* () {
+    const appPath = (0, paths_1.getAppPath)(handoff);
+    const destination = path_1.default.resolve(appPath, 'client.config.json');
+    // Ensure directory exists
+    yield fs_extra_1.default.ensureDir(appPath);
+    yield fs_extra_1.default.writeJson(destination, { config: (0, config_1.getClientConfig)(handoff.config) }, { spaces: 2 });
+});
+exports.persistClientConfig = persistClientConfig;

package/dist/app-builder/index.d.ts

@@ -0,0 +1,2 @@
+export { buildComponents } from '../pipeline/components';
+export { default, devApp, watchApp } from './build';

package/dist/app-builder/index.js

@@ -0,0 +1,12 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.watchApp = exports.devApp = exports.default = exports.buildComponents = void 0;
+var components_1 = require("../pipeline/components");
+Object.defineProperty(exports, "buildComponents", { enumerable: true, get: function () { return components_1.buildComponents; } });
+var build_1 = require("./build");
+Object.defineProperty(exports, "default", { enumerable: true, get: function () { return __importDefault(build_1).default; } });
+Object.defineProperty(exports, "devApp", { enumerable: true, get: function () { return build_1.devApp; } });
+Object.defineProperty(exports, "watchApp", { enumerable: true, get: function () { return build_1.watchApp; } });

package/dist/app-builder/paths.d.ts

@@ -0,0 +1,19 @@
+import Handoff from '..';
+/**
+ * Gets the working public directory path for a given handoff instance.
+ * Checks for both project-specific and default public directories.
+ *
+ * @param handoff - The handoff instance containing working path and figma project configuration
+ * @returns The resolved path to the public directory if it exists, null otherwise
+ */
+export declare const getWorkingPublicPath: (handoff: Handoff) => string | null;
+/**
+ * Gets the application path for a given handoff instance.
+ * @param handoff - The handoff instance containing module path and figma project configuration
+ * @returns The resolved path to the application directory
+ */
+export declare const getAppPath: (handoff: Handoff) => string;
+/**
+ * Copy the public dir from the working dir to the module dir.
+ */
+export declare const syncPublicFiles: (handoff: Handoff) => Promise<void>;

package/dist/app-builder/paths.js

@@ -0,0 +1,56 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.syncPublicFiles = exports.getAppPath = exports.getWorkingPublicPath = void 0;
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const path_1 = __importDefault(require("path"));
+/**
+ * Gets the working public directory path for a given handoff instance.
+ * Checks for both project-specific and default public directories.
+ *
+ * @param handoff - The handoff instance containing working path and figma project configuration
+ * @returns The resolved path to the public directory if it exists, null otherwise
+ */
+const getWorkingPublicPath = (handoff) => {
+    const paths = [path_1.default.resolve(handoff.workingPath, `public-${handoff.getProjectId()}`), path_1.default.resolve(handoff.workingPath, `public`)];
+    for (const p of paths) {
+        if (fs_extra_1.default.existsSync(p)) {
+            return p;
+        }
+    }
+    return null;
+};
+exports.getWorkingPublicPath = getWorkingPublicPath;
+/**
+ * Gets the application path for a given handoff instance.
+ * @param handoff - The handoff instance containing module path and figma project configuration
+ * @returns The resolved path to the application directory
+ */
+const getAppPath = (handoff) => {
+    return path_1.default.resolve(handoff.modulePath, '.handoff', `${handoff.getProjectId()}`);
+};
+exports.getAppPath = getAppPath;
+/**
+ * Copy the public dir from the working dir to the module dir.
+ */
+const syncPublicFiles = (handoff) => __awaiter(void 0, void 0, void 0, function* () {
+    const appPath = (0, exports.getAppPath)(handoff);
+    const workingPublicPath = (0, exports.getWorkingPublicPath)(handoff);
+    if (workingPublicPath) {
+        yield fs_extra_1.default.copy(workingPublicPath, path_1.default.resolve(appPath, 'public'), {
+            overwrite: true,
+        });
+    }
+});
+exports.syncPublicFiles = syncPublicFiles;

package/dist/app-builder/watchers.d.ts

@@ -0,0 +1,45 @@
+import chokidar from 'chokidar';
+import Handoff from '..';
+import { ComponentSegment } from '../transformers/preview/component/builder';
+import { ComponentListObject } from '../transformers/preview/types';
+export interface WatcherState {
+    debounce: boolean;
+    runtimeComponentsWatcher: chokidar.FSWatcher | null;
+    runtimeConfigurationWatcher: chokidar.FSWatcher | null;
+}
+/**
+ * Watches the working public directory for changes and updates the app.
+ */
+export declare const watchPublicDirectory: (handoff: Handoff, wss: (msg: string) => void, state: WatcherState, chokidarConfig: chokidar.WatchOptions) => void;
+/**
+ * Watches the application source code for changes.
+ */
+export declare const watchAppSource: (handoff: Handoff, initializeProjectApp: (handoff: Handoff) => Promise<string>) => void;
+/**
+ * Watches the user's pages directory for changes.
+ */
+export declare const watchPages: (handoff: Handoff, chokidarConfig: chokidar.WatchOptions) => void;
+/**
+ * Watches global SCSS and JS entry points for changes.
+ * Rebuilds the main bundles and all components when a global entry changes,
+ * since per-component builds may depend on these shared entries.
+ */
+export declare const watchGlobalEntries: (handoff: Handoff, state: WatcherState, chokidarConfig: chokidar.WatchOptions) => void;
+/**
+ * Maps configuration entry types to component segments.
+ */
+export declare const mapEntryTypeToSegment: (type: keyof ComponentListObject["entries"]) => ComponentSegment | undefined;
+/**
+ * Gets the paths of runtime components to watch.
+ *
+ * @returns A Map of paths to watch and their entry types
+ */
+export declare const getRuntimeComponentsPathsToWatch: (handoff: Handoff) => Map<string, "template" | "js" | "scss">;
+/**
+ * Watches runtime components for changes.
+ */
+export declare const watchRuntimeComponents: (handoff: Handoff, state: WatcherState, runtimeComponentPathsToWatch: Map<string, keyof ComponentListObject["entries"]>) => void;
+/**
+ * Watches the runtime configuration for changes.
+ */
+export declare const watchRuntimeConfiguration: (handoff: Handoff, state: WatcherState) => void;