handoff-app 1.1.3 → 1.2.0-0

package/config/config.template.js

@@ -1,8 +1,11 @@
-/** @type {import('handoff-app').Config} */
 const path = require('path');
-module.exports = {
+const { defineConfig } = require('handoff-app');
+/** @typedef {import('handoff-app').Config} HandoffConfig */
+
+/** @type {HandoffConfig} */
+const config = {
   // Set your Figma project ID here or in the environment variable HANDOFF_FIGMA_PROJECT_ID
-  figma_project_id: null,
+  figmaProjectId: null,
   // Set the output directory for the exported components
   exportsOutputDirectory: 'exported',
   // Set the output directory for the sites
@@ -16,13 +19,13 @@ module.exports = {
     // Set the client for the application, used in the footer
     client: 'Handoff Technologies',
     // Set the Google Tag Manager ID to add GTM scripts
-    google_tag_manager: null,
+    googleTagManager: null,
     // Set the attribution for the application
     attribution: true, // Should we remove this?
     // Set the type copy for the typeography page
-    type_copy: 'Almost before we knew it, we had left the ground.',
+    typeCopy: 'Almost before we knew it, we had left the ground.',
     // Set the type sort for the typeography page
-    type_sort: [
+    typeSort: [
       'Heading 1',
       'Heading 2',
       'Heading 3',
@@ -36,17 +39,16 @@ module.exports = {
       'Link',
     ],
     // Set the color sort for the color page
-    color_sort: ['primary', 'secondary', 'extra', 'system'],
+    colorSort: ['primary', 'secondary', 'extra', 'system'],
     // Set the component sort for the component page
-    component_sort: ['primary', 'secondary', 'transparent'],
+    componentSort: ['primary', 'secondary', 'transparent'],
     // Set the base path for the application
-    base_path: '',
+    basePath: '',
     // Set the breakpoints for the application
     breakpoints: {
-      sm: { size: 576, name: 'Small' },
-      md: { size: 768, name: 'Medium' },
-      lg: { size: 992, name: 'Large' },
-      xl: { size: 1200, name: 'Extra Large' },
+      mobile: { size: 400, name: 'Mobile' },
+      tablet: { size: 800, name: 'Medium' },
+      desktop: { size: 1100, name: 'Large' },
     },
     // Set the ports for the application
     ports: { app: 3000, websocket: 3001 },
@@ -56,9 +58,12 @@ module.exports = {
     scss: './sass/main.scss',
     js: './js/main.js',
     components: ['./components'],
+    // Uncomment to enable pattern documentation pages.
+    // Patterns compose component previews into single-page views.
+    // patterns: ['./patterns'],
   },
   // These are the asset zip file download links
-  assets_zip_links: {
+  assetsZipLinks: {
     icons: null,
     logos: null,
   },
@@ -86,3 +91,5 @@ module.exports = {
     },
   },
 };
+
+module.exports = defineConfig(config);

package/config/config.template.ts

@@ -0,0 +1,54 @@
+import { defineConfig } from 'handoff-app';
+
+export default defineConfig({
+  figmaProjectId: null,
+  exportsOutputDirectory: 'exported',
+  sitesOutputDirectory: 'out',
+  app: {
+    theme: 'default',
+    title: 'Handoff Design System',
+    client: 'Handoff Technologies',
+    googleTagManager: null,
+    attribution: true,
+    typeCopy: 'Almost before we knew it, we had left the ground.',
+    typeSort: [
+      'Heading 1',
+      'Heading 2',
+      'Heading 3',
+      'Heading 4',
+      'Heading 5',
+      'Heading 6',
+      'Paragraph',
+      'Subheading',
+      'Blockquote',
+      'Input Labels',
+      'Link',
+    ],
+    colorSort: ['primary', 'secondary', 'extra', 'system'],
+    componentSort: ['primary', 'secondary', 'transparent'],
+    basePath: '',
+    breakpoints: {
+      mobile: { size: 400, name: 'Mobile' },
+      tablet: { size: 800, name: 'Medium' },
+      desktop: { size: 1100, name: 'Large' },
+    },
+    ports: { app: 3000, websocket: 3001 },
+  },
+  entries: {
+    scss: './sass/main.scss',
+    js: './js/main.js',
+    components: ['./components'],
+    // patterns: ['./patterns'],
+  },
+  assetsZipLinks: {
+    icons: null,
+    logos: null,
+  },
+  hooks: {
+    cssBuildConfig: (config) => config,
+    validateComponent: () => ({}),
+    clientBuildConfig: (config) => config,
+    htmlBuildConfig: (config) => config,
+    jsBuildConfig: (config) => config,
+  },
+});

package/config/docs/system.md

@@ -16,4 +16,6 @@ menu:
     tokens: true
   - title: Components
     components: true
+  - title: Patterns
+    patterns: true
 ---

package/dist/app-builder/build.js

@@ -17,6 +17,7 @@ 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 patterns_1 = require("../pipeline/patterns");
 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"));
@@ -95,9 +96,10 @@ const buildApp = (handoff, skipComponents) => __awaiter(void 0, void 0, void 0,
     skipComponents = skipComponents !== null && skipComponents !== void 0 ? skipComponents : false;
     // Perform cleanup
     yield cleanupAppDirectory(handoff);
-    // Build components
+    // Build components, then patterns (patterns depend on component output)
     if (!skipComponents) {
         yield (0, components_1.buildComponents)(handoff);
+        yield (0, patterns_1.buildPatterns)(handoff);
     }
     // Prepare app
     const appPath = yield initializeProjectApp(handoff);
@@ -137,6 +139,8 @@ const watchApp = (handoff) => __awaiter(void 0, void 0, void 0, function* () {
     yield (0, builder_1.default)(handoff, undefined, undefined, { useCache: true });
     yield (0, javascript_1.buildMainJS)(handoff);
     yield (0, css_1.buildMainCss)(handoff);
+    // Build patterns after components are ready
+    yield (0, patterns_1.buildPatterns)(handoff);
     const appPath = yield initializeProjectApp(handoff);
     // Persist client configuration
     yield (0, client_config_1.persistClientConfig)(handoff);
@@ -172,7 +176,8 @@ const watchApp = (handoff) => __awaiter(void 0, void 0, void 0, function* () {
         ignoreInitial: true,
     };
     const state = {
-        debounce: false,
+        busy: false,
+        pendingHandlers: new Map(),
         runtimeComponentsWatcher: null,
         runtimeConfigurationWatcher: null,
         componentDirectoriesWatcher: null,

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

@@ -0,0 +1,4 @@
+export type { ConfigDiffStrategy, RebuildHandle } from './types';
+export { type MapSnapshot, diffMapSnapshots, stableStringify } from './snapshot';
+export { patternDiffStrategy } from './strategies/pattern';
+export { getAllStrategies, getStrategy, runAllFinalizers } from './registry';

package/dist/app-builder/config-diff/index.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runAllFinalizers = exports.getStrategy = exports.getAllStrategies = exports.patternDiffStrategy = exports.stableStringify = exports.diffMapSnapshots = void 0;
+var snapshot_1 = require("./snapshot");
+Object.defineProperty(exports, "diffMapSnapshots", { enumerable: true, get: function () { return snapshot_1.diffMapSnapshots; } });
+Object.defineProperty(exports, "stableStringify", { enumerable: true, get: function () { return snapshot_1.stableStringify; } });
+var pattern_1 = require("./strategies/pattern");
+Object.defineProperty(exports, "patternDiffStrategy", { enumerable: true, get: function () { return pattern_1.patternDiffStrategy; } });
+var registry_1 = require("./registry");
+Object.defineProperty(exports, "getAllStrategies", { enumerable: true, get: function () { return registry_1.getAllStrategies; } });
+Object.defineProperty(exports, "getStrategy", { enumerable: true, get: function () { return registry_1.getStrategy; } });
+Object.defineProperty(exports, "runAllFinalizers", { enumerable: true, get: function () { return registry_1.runAllFinalizers; } });

package/dist/app-builder/config-diff/registry.d.ts

@@ -0,0 +1,9 @@
+import Handoff from '../..';
+import { ConfigDiffStrategy } from './types';
+export declare const getStrategy: (kind: string) => ConfigDiffStrategy | undefined;
+export declare const getAllStrategies: () => ConfigDiffStrategy[];
+/**
+ * Runs every registered strategy finalizer.
+ * Called after component rebuilds so derived artifacts stay up-to-date.
+ */
+export declare const runAllFinalizers: (handoff: Handoff) => Promise<void>;

package/dist/app-builder/config-diff/registry.js

@@ -0,0 +1,30 @@
+"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());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runAllFinalizers = exports.getAllStrategies = exports.getStrategy = void 0;
+const pattern_1 = require("./strategies/pattern");
+const strategies = new Map([
+    [pattern_1.patternDiffStrategy.kind, pattern_1.patternDiffStrategy],
+]);
+const getStrategy = (kind) => strategies.get(kind);
+exports.getStrategy = getStrategy;
+const getAllStrategies = () => Array.from(strategies.values());
+exports.getAllStrategies = getAllStrategies;
+/**
+ * Runs every registered strategy finalizer.
+ * Called after component rebuilds so derived artifacts stay up-to-date.
+ */
+const runAllFinalizers = (handoff) => __awaiter(void 0, void 0, void 0, function* () {
+    for (const strategy of strategies.values()) {
+        yield strategy.finalize(handoff);
+    }
+});
+exports.runAllFinalizers = runAllFinalizers;

package/dist/app-builder/config-diff/snapshot.d.ts

@@ -0,0 +1,13 @@
+/** outerKey -> Map<innerKey, serializedValue> */
+export type MapSnapshot = Map<string, Map<string, string>>;
+/**
+ * Deterministic JSON serializer that sorts object keys at every nesting level.
+ * Prevents false-positive diffs when identical values are constructed with
+ * different key insertion order across reloads.
+ */
+export declare const stableStringify: (value: unknown) => string;
+/**
+ * Compares two MapSnapshots and returns the outer keys where the inner maps
+ * differ (added, removed, or values changed).
+ */
+export declare const diffMapSnapshots: (oldSnapshot: MapSnapshot, newSnapshot: MapSnapshot) => string[];

package/dist/app-builder/config-diff/snapshot.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.diffMapSnapshots = exports.stableStringify = void 0;
+/**
+ * Deterministic JSON serializer that sorts object keys at every nesting level.
+ * Prevents false-positive diffs when identical values are constructed with
+ * different key insertion order across reloads.
+ */
+const stableStringify = (value) => JSON.stringify(value, (_, v) => v && typeof v === 'object' && !Array.isArray(v)
+    ? Object.fromEntries(Object.entries(v).sort(([a], [b]) => a.localeCompare(b)))
+    : v);
+exports.stableStringify = stableStringify;
+/**
+ * Compares two MapSnapshots and returns the outer keys where the inner maps
+ * differ (added, removed, or values changed).
+ */
+const diffMapSnapshots = (oldSnapshot, newSnapshot) => {
+    const affected = new Set();
+    for (const [key, oldEntries] of oldSnapshot) {
+        const newEntries = newSnapshot.get(key);
+        if (!newEntries) {
+            affected.add(key);
+            continue;
+        }
+        if (oldEntries.size !== newEntries.size) {
+            affected.add(key);
+            continue;
+        }
+        for (const [subKey, oldValue] of oldEntries) {
+            if (newEntries.get(subKey) !== oldValue) {
+                affected.add(key);
+                break;
+            }
+        }
+    }
+    for (const key of newSnapshot.keys()) {
+        if (!oldSnapshot.has(key)) {
+            affected.add(key);
+        }
+    }
+    return Array.from(affected);
+};
+exports.diffMapSnapshots = diffMapSnapshots;

package/dist/app-builder/config-diff/strategies/pattern.d.ts

@@ -0,0 +1,2 @@
+import { ConfigDiffStrategy } from '../types';
+export declare const patternDiffStrategy: ConfigDiffStrategy;

package/dist/app-builder/config-diff/strategies/pattern.js

@@ -0,0 +1,93 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+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());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.patternDiffStrategy = void 0;
+const patterns_1 = require("../../../pipeline/patterns");
+const builder_1 = __importStar(require("../../../transformers/preview/component/builder"));
+const logger_1 = require("../../../utils/logger");
+const snapshot_1 = require("../snapshot");
+/**
+ * Snapshots every __pattern_{patternId}_* synthetic preview entry across all
+ * components. Outer key is component id, inner key is synthetic preview key.
+ */
+const snapshotPatternSynthetics = (handoff, patternId) => {
+    var _a, _b, _c, _d;
+    const components = (_c = (_b = (_a = handoff.runtimeConfig) === null || _a === void 0 ? void 0 : _a.entries) === null || _b === void 0 ? void 0 : _b.components) !== null && _c !== void 0 ? _c : {};
+    const prefix = `__pattern_${patternId}_`;
+    const result = new Map();
+    for (const [componentId, component] of Object.entries(components)) {
+        const previews = (_d = component.internalPatternPreviews) !== null && _d !== void 0 ? _d : {};
+        const entries = new Map();
+        for (const [key, preview] of Object.entries(previews)) {
+            if (key.startsWith(prefix)) {
+                entries.set(key, (0, snapshot_1.stableStringify)(preview.values));
+            }
+        }
+        if (entries.size > 0) {
+            result.set(componentId, entries);
+        }
+    }
+    return result;
+};
+exports.patternDiffStrategy = {
+    kind: 'pattern',
+    capture(handoff, entityId) {
+        const oldSnapshot = snapshotPatternSynthetics(handoff, entityId);
+        return {
+            apply(handoff, entityIdAfterReload) {
+                return __awaiter(this, void 0, void 0, function* () {
+                    const newSnapshot = entityIdAfterReload
+                        ? snapshotPatternSynthetics(handoff, entityIdAfterReload)
+                        : new Map();
+                    const affectedIds = (0, snapshot_1.diffMapSnapshots)(oldSnapshot, newSnapshot);
+                    const displayId = entityIdAfterReload || entityId;
+                    if (affectedIds.length > 0) {
+                        logger_1.Logger.debug(`Pattern "${displayId}" changed: rebuilding ${affectedIds.length} affected component(s): ${affectedIds.join(', ')}`);
+                        for (const componentId of affectedIds) {
+                            yield (0, builder_1.default)(handoff, componentId, builder_1.ComponentSegment.Previews);
+                        }
+                    }
+                    else {
+                        logger_1.Logger.debug(`Pattern "${displayId}" changed: no synthetic previews affected, skipping component rebuild.`);
+                    }
+                });
+            },
+        };
+    },
+    finalize(handoff) {
+        return __awaiter(this, void 0, void 0, function* () {
+            yield (0, patterns_1.buildPatterns)(handoff);
+        });
+    },
+};

package/dist/app-builder/config-diff/types.d.ts

@@ -0,0 +1,19 @@
+import Handoff from '../..';
+/**
+ * Handle returned by ConfigDiffStrategy.capture().
+ *
+ * Captures the pre-reload state in a closure so the snapshot type stays
+ * fully encapsulated and the watcher only sees this opaque handle.
+ */
+export interface RebuildHandle {
+    apply(handoff: Handoff, entityIdAfterReload: string | undefined): Promise<void>;
+}
+/**
+ * Encapsulates the snapshot -> reload -> diff -> selective-rebuild protocol
+ * for a single config-file entity kind.
+ */
+export interface ConfigDiffStrategy {
+    readonly kind: string;
+    capture(handoff: Handoff, entityId: string): RebuildHandle;
+    finalize(handoff: Handoff): Promise<void>;
+}

package/dist/app-builder/config-diff/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

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

@@ -0,0 +1,15 @@
+import Handoff from '../..';
+import { ComponentSegment } from '../../transformers/preview/component/builder';
+import { ComponentListObject } from '../../transformers/preview/types';
+export type RuntimeComponentEntryType = keyof ComponentListObject['entries'];
+/**
+ * Maps configuration entry types to component segments.
+ */
+export declare const mapEntryTypeToSegment: (type: RuntimeComponentEntryType) => ComponentSegment | undefined;
+export declare const resolveComponentIdForChangedFile: (handoff: Handoff, changedFilePath: string) => string | 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, RuntimeComponentEntryType>;

package/dist/app-builder/watchers/component.js

@@ -0,0 +1,69 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getRuntimeComponentsPathsToWatch = exports.resolveComponentIdForChangedFile = exports.mapEntryTypeToSegment = void 0;
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const path_1 = __importDefault(require("path"));
+const builder_1 = require("../../transformers/preview/component/builder");
+const path_2 = require("../../utils/path");
+/**
+ * Maps configuration entry types to component segments.
+ */
+const mapEntryTypeToSegment = (type) => {
+    return {
+        js: builder_1.ComponentSegment.JavaScript,
+        scss: builder_1.ComponentSegment.Style,
+        template: builder_1.ComponentSegment.Previews,
+        templates: builder_1.ComponentSegment.Previews,
+        component: builder_1.ComponentSegment.Previews,
+        story: builder_1.ComponentSegment.Previews,
+    }[type];
+};
+exports.mapEntryTypeToSegment = mapEntryTypeToSegment;
+const resolveComponentIdForChangedFile = (handoff, changedFilePath) => {
+    var _a, _b, _c, _d;
+    const normalizedChangedPath = (0, path_2.normalizePathForCompare)(changedFilePath);
+    const runtimeComponents = (_c = (_b = (_a = handoff.runtimeConfig) === null || _a === void 0 ? void 0 : _a.entries) === null || _b === void 0 ? void 0 : _b.components) !== null && _c !== void 0 ? _c : {};
+    for (const [componentId, componentDef] of Object.entries(runtimeComponents)) {
+        const entries = (_d = componentDef.entries) !== null && _d !== void 0 ? _d : {};
+        for (const entryPath of Object.values(entries)) {
+            if (!entryPath)
+                continue;
+            const normalizedEntryPath = (0, path_2.normalizePathForCompare)(entryPath);
+            if (normalizedEntryPath === normalizedChangedPath) {
+                return componentId;
+            }
+        }
+    }
+    // Fallback for legacy path conventions when exact match is unavailable.
+    return path_1.default.basename(path_1.default.dirname(changedFilePath));
+};
+exports.resolveComponentIdForChangedFile = resolveComponentIdForChangedFile;
+/**
+ * Gets the paths of runtime components to watch.
+ *
+ * @returns A map of paths to watch and their entry types.
+ */
+const getRuntimeComponentsPathsToWatch = (handoff) => {
+    var _a, _b, _c;
+    const result = new Map();
+    for (const runtimeComponentId of Object.keys((_b = (_a = handoff.runtimeConfig) === null || _a === void 0 ? void 0 : _a.entries.components) !== null && _b !== void 0 ? _b : {})) {
+        const runtimeComponent = handoff.runtimeConfig.entries.components[runtimeComponentId];
+        for (const [runtimeComponentEntryType, runtimeComponentEntryPath] of Object.entries((_c = runtimeComponent.entries) !== null && _c !== void 0 ? _c : {})) {
+            const normalizedComponentEntryPath = runtimeComponentEntryPath;
+            if (fs_extra_1.default.existsSync(normalizedComponentEntryPath)) {
+                const entryType = runtimeComponentEntryType;
+                if (fs_extra_1.default.statSync(normalizedComponentEntryPath).isFile()) {
+                    result.set(path_1.default.resolve(normalizedComponentEntryPath), entryType);
+                }
+                else {
+                    result.set(normalizedComponentEntryPath, entryType);
+                }
+            }
+        }
+    }
+    return result;
+};
+exports.getRuntimeComponentsPathsToWatch = getRuntimeComponentsPathsToWatch;

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

@@ -0,0 +1,14 @@
+import chokidar from 'chokidar';
+export interface WatcherState {
+    busy: boolean;
+    pendingHandlers: Map<string, () => Promise<void>>;
+    runtimeComponentsWatcher: chokidar.FSWatcher | null;
+    runtimeConfigurationWatcher: chokidar.FSWatcher | null;
+    componentDirectoriesWatcher: chokidar.FSWatcher | null;
+}
+/**
+ * Schedules a handler for execution with mutual exclusion and per-source
+ * coalescing. When the lock is free the handler runs immediately. When busy,
+ * only the latest handler per source key is kept.
+ */
+export declare const scheduleHandler: (state: WatcherState, source: string, handler: () => Promise<void>) => Promise<void>;

package/dist/app-builder/watchers/utils.js

@@ -0,0 +1,44 @@
+"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());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.scheduleHandler = void 0;
+const logger_1 = require("../../utils/logger");
+/**
+ * Schedules a handler for execution with mutual exclusion and per-source
+ * coalescing. When the lock is free the handler runs immediately. When busy,
+ * only the latest handler per source key is kept.
+ */
+const scheduleHandler = (state, source, handler) => __awaiter(void 0, void 0, void 0, function* () {
+    if (state.busy) {
+        state.pendingHandlers.set(source, handler);
+        return;
+    }
+    state.busy = true;
+    try {
+        yield handler();
+        while (state.pendingHandlers.size > 0) {
+            const entries = Array.from(state.pendingHandlers.entries());
+            state.pendingHandlers.clear();
+            for (const [pendingSource, pendingHandler] of entries) {
+                try {
+                    yield pendingHandler();
+                }
+                catch (e) {
+                    logger_1.Logger.error(`Unhandled error in scheduled handler for source "${pendingSource}":`, e);
+                }
+            }
+        }
+    }
+    finally {
+        state.busy = false;
+    }
+});
+exports.scheduleHandler = scheduleHandler;

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

@@ -1,13 +1,9 @@
 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;
-    componentDirectoriesWatcher: chokidar.FSWatcher | null;
-}
+import { RuntimeComponentEntryType } from './watchers/component';
+import { WatcherState } from './watchers/utils';
+export { getRuntimeComponentsPathsToWatch, mapEntryTypeToSegment } from './watchers/component';
+export type { WatcherState } from './watchers/utils';
 /**
  * Watches the working public directory for changes and updates the app.
  */
@@ -26,22 +22,17 @@ export declare const watchPages: (handoff: Handoff, chokidarConfig: chokidar.Wat
  * 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;
+export declare const watchRuntimeComponents: (handoff: Handoff, state: WatcherState, runtimeComponentPathsToWatch: Map<string, RuntimeComponentEntryType>) => void;
 /**
  * Watches the runtime configuration for changes.
+ *
+ * Uses the generic {@link ConfigDiffStrategy} registry so that each entity
+ * kind (patterns today, potentially themes / slots later) supplies its own
+ * snapshot → diff → selective-rebuild logic without the watcher needing to
+ * know the details.
  */
 export declare const watchRuntimeConfiguration: (handoff: Handoff, state: WatcherState) => void;
 /**