handoff-app 1.2.0-0 → 1.2.0-2

package/dist/transformers/preview/component/artifacts.js

@@ -0,0 +1,126 @@
+"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.syncComponentArtifacts = exports.removeComponentApi = exports.getComponentApiPath = void 0;
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const path_1 = __importDefault(require("path"));
+const previews_1 = require("./previews");
+const api_1 = require("./api");
+const css_1 = require("./css");
+const javascript_1 = require("./javascript");
+const COMPONENT_JS_RESERVED_FILES = new Set([javascript_1.MAIN_COMPONENT_JS_FILE]);
+const COMPONENT_CSS_RESERVED_FILES = new Set([css_1.MAIN_COMPONENT_CSS_FILE, css_1.SHARED_COMPONENT_CSS_FILE]);
+const getComponentApiPath = (handoff) => path_1.default.resolve((0, api_1.getAPIPath)(handoff), 'component');
+exports.getComponentApiPath = getComponentApiPath;
+const getComponentPreviewKeys = (handoff, componentId) => __awaiter(void 0, void 0, void 0, function* () {
+    var _a, _b, _c;
+    const runtimeComponent = (_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 ? void 0 : _c[componentId];
+    const previewKeys = new Set();
+    const outputFilePath = path_1.default.resolve((0, exports.getComponentApiPath)(handoff), `${componentId}.json`);
+    if (fs_extra_1.default.existsSync(outputFilePath)) {
+        try {
+            const existingJson = yield fs_extra_1.default.readFile(outputFilePath, 'utf8');
+            if (existingJson) {
+                const existingData = (0, api_1.sanitizeComponentApiData)(JSON.parse(existingJson));
+                for (const previewKey of Object.keys((existingData === null || existingData === void 0 ? void 0 : existingData.previews) || {})) {
+                    previewKeys.add(previewKey);
+                }
+            }
+        }
+        catch (_d) {
+            // Fall back to runtime config below.
+        }
+    }
+    for (const previewKey of Object.keys((0, previews_1.getDocumentedPreviews)(runtimeComponent === null || runtimeComponent === void 0 ? void 0 : runtimeComponent.previews) || {})) {
+        previewKeys.add(previewKey);
+    }
+    for (const previewKey of Object.keys((runtimeComponent === null || runtimeComponent === void 0 ? void 0 : runtimeComponent.internalPatternPreviews) || {})) {
+        previewKeys.add(previewKey);
+    }
+    return previewKeys;
+});
+const getArtifactComponentId = (fileName, componentIds) => {
+    let match = null;
+    for (const componentId of componentIds) {
+        if (!fileName.startsWith(`${componentId}-`))
+            continue;
+        if (!match || componentId.length > match.length) {
+            match = componentId;
+        }
+    }
+    return match;
+};
+const removeComponentApi = (handoff, id) => __awaiter(void 0, void 0, void 0, function* () {
+    const outputDirPath = (0, exports.getComponentApiPath)(handoff);
+    const outputFilePath = path_1.default.resolve(outputDirPath, `${id}.json`);
+    if (yield fs_extra_1.default.pathExists(outputFilePath)) {
+        yield fs_extra_1.default.remove(outputFilePath);
+    }
+});
+exports.removeComponentApi = removeComponentApi;
+const syncComponentArtifacts = (handoff) => __awaiter(void 0, void 0, void 0, function* () {
+    var _a, _b, _c;
+    const componentPath = (0, exports.getComponentApiPath)(handoff);
+    yield fs_extra_1.default.ensureDir(componentPath);
+    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 : {};
+    const runtimeIds = Object.keys(runtimeComponents);
+    const entries = yield fs_extra_1.default.readdir(componentPath);
+    const discoveredArtifactIds = new Set(runtimeIds);
+    for (const entry of entries) {
+        const parsed = path_1.default.parse(entry);
+        if (parsed.ext === '.json' || parsed.ext === '.js' || parsed.ext === '.css') {
+            if (!COMPONENT_JS_RESERVED_FILES.has(entry) && !COMPONENT_CSS_RESERVED_FILES.has(entry)) {
+                discoveredArtifactIds.add(parsed.name);
+            }
+        }
+    }
+    const validFiles = new Set();
+    for (const componentId of runtimeIds) {
+        validFiles.add(`${componentId}.json`);
+        if (yield fs_extra_1.default.pathExists(path_1.default.resolve(componentPath, `${componentId}.js`))) {
+            validFiles.add(`${componentId}.js`);
+        }
+        if (yield fs_extra_1.default.pathExists(path_1.default.resolve(componentPath, `${componentId}.css`))) {
+            validFiles.add(`${componentId}.css`);
+        }
+        const previewKeys = yield getComponentPreviewKeys(handoff, componentId);
+        for (const previewKey of previewKeys) {
+            validFiles.add(`${componentId}-${previewKey}.html`);
+            validFiles.add(`${componentId}-${previewKey}-inspect.html`);
+        }
+    }
+    for (const entry of entries) {
+        if (COMPONENT_JS_RESERVED_FILES.has(entry) || COMPONENT_CSS_RESERVED_FILES.has(entry)) {
+            continue;
+        }
+        const parsed = path_1.default.parse(entry);
+        if (parsed.ext === '.json' || parsed.ext === '.js' || parsed.ext === '.css') {
+            if (!validFiles.has(entry)) {
+                yield fs_extra_1.default.remove(path_1.default.resolve(componentPath, entry));
+            }
+            continue;
+        }
+        if (parsed.ext !== '.html') {
+            continue;
+        }
+        const ownerId = getArtifactComponentId(entry, discoveredArtifactIds);
+        if (!ownerId) {
+            continue;
+        }
+        if (!validFiles.has(entry)) {
+            yield fs_extra_1.default.remove(path_1.default.resolve(componentPath, entry));
+        }
+    }
+});
+exports.syncComponentArtifacts = syncComponentArtifacts;

package/dist/transformers/preview/component/builder.js

@@ -27,11 +27,14 @@ exports.ComponentSegment = void 0;
 exports.processComponents = processComponents;
 const cloneDeep_1 = __importDefault(require("lodash/cloneDeep"));
 const cache_1 = require("../../../cache");
+const duration_1 = require("../../../utils/duration");
 const logger_1 = require("../../../utils/logger");
 const schema_1 = require("../../utils/schema");
 const types_1 = require("../types");
 const api_1 = require("./api");
+const artifacts_1 = require("./artifacts");
 const previews_1 = require("./previews");
+const summary_1 = require("./summary");
 const css_1 = __importDefault(require("./css"));
 const html_1 = __importDefault(require("./html"));
 const javascript_1 = __importDefault(require("./javascript"));
@@ -83,6 +86,37 @@ const ensureDefaultPreview = (data) => {
 const getBuildPreviews = (data) => {
     return Object.assign(Object.assign({}, ((data === null || data === void 0 ? void 0 : data.previews) || {})), ((data === null || data === void 0 ? void 0 : data.internalPatternPreviews) || {}));
 };
+/** Vite-backed segments in execution order; extend here if new steps are added. */
+const VITE_BUILD_SEGMENTS = [
+    { key: 'js', label: 'script' },
+    { key: 'css', label: 'styles' },
+    { key: 'previews', label: 'previews' },
+];
+const isFullViteComponentBuild = (plan) => plan.js && plan.css && plan.previews;
+const getActiveViteBuildLabels = (plan) => VITE_BUILD_SEGMENTS.filter(({ key }) => plan[key]).map(({ label }) => label);
+/** e.g. "a", "a and b", "a, b, and c" — common CLI copy style. */
+const formatEnglishList = (items) => {
+    if (items.length === 0)
+        return '';
+    if (items.length === 1)
+        return items[0];
+    if (items.length === 2)
+        return `${items[0]} and ${items[1]}`;
+    return `${items.slice(0, -1).join(', ')}, and ${items[items.length - 1]}`;
+};
+const viteBuildStartMessage = (componentId, plan) => {
+    if (isFullViteComponentBuild(plan)) {
+        return `Building component "${componentId}"…`;
+    }
+    return `Building ${formatEnglishList(getActiveViteBuildLabels(plan))} for component "${componentId}"…`;
+};
+const viteBuildFinishMessage = (componentId, plan, elapsedMs) => {
+    const duration = (0, duration_1.formatDurationMs)(elapsedMs);
+    if (isFullViteComponentBuild(plan)) {
+        return `Finished building component "${componentId}" in ${duration}`;
+    }
+    return `Finished building ${formatEnglishList(getActiveViteBuildLabels(plan))} for component "${componentId}" in ${duration}`;
+};
 /**
  * Returns a normalized build plan describing which component segments need rebuilding.
  *
@@ -121,6 +155,12 @@ function processComponents(handoff, id, segmentToProcess, options) {
         const components = (_a = documentationObject === null || documentationObject === void 0 ? void 0 : documentationObject.components) !== null && _a !== void 0 ? _a : {};
         const runtimeComponents = (_d = (_c = (_b = handoff.runtimeConfig) === null || _b === void 0 ? void 0 : _b.entries) === null || _c === void 0 ? void 0 : _c.components) !== null && _d !== void 0 ? _d : {};
         const allComponentIds = Object.keys(runtimeComponents);
+        if (id && !runtimeComponents[id]) {
+            yield (0, artifacts_1.removeComponentApi)(handoff, id);
+            yield (0, summary_1.removeComponentFromSummaryApi)(handoff, id);
+            yield (0, artifacts_1.syncComponentArtifacts)(handoff);
+            return [];
+        }
         // Determine which components need building based on cache (when enabled)
         let componentsToBuild;
         let cache = null;
@@ -170,12 +210,17 @@ function processComponents(handoff, id, segmentToProcess, options) {
             if (cache) {
                 (0, cache_1.pruneRemovedComponents)(cache, allComponentIds);
             }
-            const skippedCount = allComponentIds.length - componentsToBuild.size;
-            if (skippedCount > 0) {
-                logger_1.Logger.info(`Building ${componentsToBuild.size} of ${allComponentIds.length} components (${skippedCount} unchanged)`);
+            const total = allComponentIds.length;
+            const toBuildCount = componentsToBuild.size;
+            const skippedCount = total - toBuildCount;
+            if (total > 0 && toBuildCount === 0) {
+                logger_1.Logger.info(`All ${total} components unchanged; skipping build`);
+            }
+            else if (skippedCount > 0 && toBuildCount > 0) {
+                logger_1.Logger.info(`Building ${toBuildCount} of ${total} components (${skippedCount} unchanged)`);
             }
-            else if (componentsToBuild.size > 0) {
-                logger_1.Logger.info(`Building all ${componentsToBuild.size} components`);
+            else if (toBuildCount > 0) {
+                logger_1.Logger.info(`Building all ${toBuildCount} components`);
             }
             else {
                 logger_1.Logger.info('All components up to date, nothing to build');
@@ -266,6 +311,12 @@ function processComponents(handoff, id, segmentToProcess, options) {
             }
             // Components should always have at least one preview variation.
             ensureDefaultPreview(data);
+            const runsViteBuildSteps = buildPlan.js || buildPlan.css || buildPlan.previews;
+            let viteBuildStartedAtMs = 0;
+            if (runsViteBuildSteps) {
+                viteBuildStartedAtMs = Date.now();
+                logger_1.Logger.info(viteBuildStartMessage(runtimeComponentId, buildPlan));
+            }
             // Build JS if needed (new build, validation missing, or explicit segment request).
             if (buildPlan.js) {
                 data = yield (0, javascript_1.default)(data, handoff);
@@ -278,6 +329,10 @@ function processComponents(handoff, id, segmentToProcess, options) {
             if (buildPlan.previews) {
                 data = yield (0, html_1.default)(Object.assign(Object.assign({}, data), { previews: getBuildPreviews(data) }), handoff, components);
             }
+            if (runsViteBuildSteps) {
+                const elapsedMs = Date.now() - viteBuildStartedAtMs;
+                logger_1.Logger.info(viteBuildFinishMessage(runtimeComponentId, buildPlan, elapsedMs));
+            }
             /**
              * Run validation if explicitly requested and a hook is configured.
              * This allows custom logic to assess the validity of the generated component data.
@@ -320,7 +375,8 @@ function processComponents(handoff, id, segmentToProcess, options) {
         }
         // Always merge and write summary file, even if no components processed
         const isFullRebuild = !id;
-        yield (0, api_1.updateComponentSummaryApi)(handoff, result, isFullRebuild);
+        yield (0, summary_1.updateComponentSummaryApi)(handoff, result, isFullRebuild);
+        yield (0, artifacts_1.syncComponentArtifacts)(handoff);
         return result;
     });
 }

package/dist/transformers/preview/component/css.d.ts

@@ -1,5 +1,7 @@
 import Handoff from '../../../index';
 import { TransformComponentTokensResult } from '../types';
+export declare const MAIN_COMPONENT_CSS_FILE = "main.css";
+export declare const SHARED_COMPONENT_CSS_FILE = "shared.css";
 declare const buildComponentCss: (data: TransformComponentTokensResult, handoff: Handoff) => Promise<{
     id: string;
     type?: import("../types").ComponentType;

package/dist/transformers/preview/component/css.js

@@ -12,15 +12,18 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.buildMainCss = void 0;
+exports.buildMainCss = exports.SHARED_COMPONENT_CSS_FILE = exports.MAIN_COMPONENT_CSS_FILE = void 0;
 const fs_extra_1 = __importDefault(require("fs-extra"));
 const path_1 = __importDefault(require("path"));
 const vite_1 = require("vite");
 const config_1 = require("../../../config");
+const duration_1 = require("../../../utils/duration");
 const logger_1 = require("../../../utils/logger");
 const vite_config_1 = __importDefault(require("../../vite-config"));
 const component_1 = require("../component");
 const { pathToFileURL } = require('url');
+exports.MAIN_COMPONENT_CSS_FILE = 'main.css';
+exports.SHARED_COMPONENT_CSS_FILE = 'shared.css';
 /**
  * Builds a CSS bundle using Vite
  *
@@ -90,17 +93,26 @@ const buildComponentCss = (data, handoff) => __awaiter(void 0, void 0, void 0, f
     var _a, _b, _c;
     const id = data.id;
     logger_1.Logger.debug(`buildComponentCss`, id);
+    const outputPath = (0, component_1.getComponentOutputPath)(handoff);
+    const builtCssPath = path_1.default.resolve(outputPath, `${id}.css`);
     const entry = (_a = data.entries) === null || _a === void 0 ? void 0 : _a.scss;
     if (!entry) {
+        // Keep generated output aligned with the current component declaration.
+        yield fs_extra_1.default.remove(builtCssPath);
+        delete data['css'];
+        delete data['sass'];
+        delete data['sharedStyles'];
         return data;
     }
     const extension = path_1.default.extname(entry);
     if (!extension) {
         return data;
     }
-    const outputPath = (0, component_1.getComponentOutputPath)(handoff);
     try {
         if (extension === '.scss' || extension === '.css') {
+            // Remove the previous artifact before rebuilding so "no emitted CSS"
+            // doesn't silently preserve stale output from an earlier build.
+            yield fs_extra_1.default.remove(builtCssPath);
             // Read the original source
             const sourceContent = yield fs_extra_1.default.readFile(entry, 'utf8');
             if (extension === '.scss') {
@@ -123,7 +135,6 @@ const buildComponentCss = (data, handoff) => __awaiter(void 0, void 0, void 0, f
                 handoff,
             });
             // Read the built CSS
-            const builtCssPath = path_1.default.resolve(outputPath, `${id}.css`);
             if (fs_extra_1.default.existsSync(builtCssPath)) {
                 const builtCss = yield fs_extra_1.default.readFile(builtCssPath, 'utf8');
                 data['css'] = builtCss;
@@ -133,9 +144,13 @@ const buildComponentCss = (data, handoff) => __awaiter(void 0, void 0, void 0, f
                 if (splitCSS && splitCSS.length > 1) {
                     data['css'] = splitCSS[1];
                     data['sharedStyles'] = splitCSS[0];
-                    yield fs_extra_1.default.writeFile(path_1.default.resolve(outputPath, 'shared.css'), data['sharedStyles']);
+                    yield fs_extra_1.default.writeFile(path_1.default.resolve(outputPath, exports.SHARED_COMPONENT_CSS_FILE), data['sharedStyles']);
                 }
             }
+            else {
+                delete data['css'];
+                delete data['sharedStyles'];
+            }
         }
     }
     catch (e) {
@@ -155,9 +170,9 @@ const buildMainCss = (handoff) => __awaiter(void 0, void 0, void 0, function* ()
         const stat = yield fs_extra_1.default.stat(runtimeConfig.entries.scss);
         const entryPath = stat.isDirectory() ? path_1.default.resolve(runtimeConfig.entries.scss, 'main.scss') : runtimeConfig.entries.scss;
         if (entryPath === runtimeConfig.entries.scss || fs_extra_1.default.existsSync(entryPath)) {
-            logger_1.Logger.success(`Building main CSS file...`);
+            logger_1.Logger.info(`Building styles for global entry (${exports.MAIN_COMPONENT_CSS_FILE})…`);
+            const startedAt = Date.now();
             try {
-                // Setup SASS load paths
                 const loadPaths = [
                     path_1.default.resolve(handoff.workingPath),
                     path_1.default.resolve(handoff.workingPath, handoff.exportsDirectory, handoff.getProjectId()),
@@ -169,13 +184,14 @@ const buildMainCss = (handoff) => __awaiter(void 0, void 0, void 0, function* ()
                 yield buildCssBundle({
                     entry: entryPath,
                     outputPath,
-                    outputFilename: 'main.css',
+                    outputFilename: exports.MAIN_COMPONENT_CSS_FILE,
                     loadPaths,
                     handoff,
                 });
+                logger_1.Logger.info(`Finished building styles for global entry (${exports.MAIN_COMPONENT_CSS_FILE}) in ${(0, duration_1.formatDurationMs)(Date.now() - startedAt)}`);
             }
-            catch (e) {
-                logger_1.Logger.error(`Failed to build main CSS:`, e);
+            catch (_d) {
+                // buildCssBundle already logs failure for the entry path
             }
         }
     }

package/dist/transformers/preview/component/javascript.d.ts

@@ -1,5 +1,6 @@
 import Handoff from '../../../index';
 import { TransformComponentTokensResult } from '../types';
+export declare const MAIN_COMPONENT_JS_FILE = "main.js";
 /**
  * Builds the JavaScript file for a single component if it exists.
  * Reads the component JavaScript file, bundles it using the buildJsBundle utility,
@@ -18,7 +19,6 @@ export declare const buildComponentJs: (data: TransformComponentTokensResult, ha
  *
  * @param handoff - The Handoff configuration object containing build settings
  * @returns A Promise that resolves when the build process is complete
- * @throws May throw an error if the build process fails
  */
 export declare const buildMainJS: (handoff: Handoff) => Promise<void>;
 export default buildComponentJs;

package/dist/transformers/preview/component/javascript.js

@@ -12,14 +12,16 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.buildMainJS = exports.buildComponentJs = void 0;
+exports.buildMainJS = exports.buildComponentJs = exports.MAIN_COMPONENT_JS_FILE = void 0;
 const fs_extra_1 = __importDefault(require("fs-extra"));
 const path_1 = __importDefault(require("path"));
 const vite_1 = require("vite");
 const config_1 = require("../../../config");
+const duration_1 = require("../../../utils/duration");
 const logger_1 = require("../../../utils/logger");
 const vite_config_1 = __importDefault(require("../../vite-config"));
 const component_1 = require("../component");
+exports.MAIN_COMPONENT_JS_FILE = 'main.js';
 /**
  * Builds a JavaScript bundle using Vite
  *
@@ -50,9 +52,6 @@ const buildJsBundle = (_a, handoff_1) => __awaiter(void 0, [_a, handoff_1], void
         }
         yield (0, vite_1.build)(viteConfig);
     }
-    catch (e) {
-        logger_1.Logger.error(`Failed to build JS for "${outputFilename}":`, e);
-    }
     finally {
         // Restore the original NODE_ENV value after vite build completes
         // This prevents interference with Next.js app building/running processes
@@ -77,20 +76,40 @@ const buildJsBundle = (_a, handoff_1) => __awaiter(void 0, [_a, handoff_1], void
 const buildComponentJs = (data, handoff) => __awaiter(void 0, void 0, void 0, function* () {
     var _a;
     const id = data.id;
+    const outputPath = (0, component_1.getComponentOutputPath)(handoff);
+    const builtJsPath = path_1.default.resolve(outputPath, `${id}.js`);
     const entry = (_a = data.entries) === null || _a === void 0 ? void 0 : _a.js;
-    if (!entry)
+    if (!entry) {
+        // Keep generated output aligned with the current component declaration.
+        yield fs_extra_1.default.remove(builtJsPath);
+        delete data.js;
+        delete data['jsCompiled'];
         return data;
-    const outputPath = (0, component_1.getComponentOutputPath)(handoff);
+    }
     try {
+        // Remove the previous artifact before rebuilding so a no-output build
+        // cannot accidentally preserve stale compiled JS.
+        yield fs_extra_1.default.remove(builtJsPath);
         const js = yield fs_extra_1.default.readFile(path_1.default.resolve(entry), 'utf8');
-        yield buildJsBundle({
-            entry,
-            outputPath,
-            outputFilename: `${id}.js`,
-        }, handoff);
+        try {
+            yield buildJsBundle({
+                entry,
+                outputPath,
+                outputFilename: `${id}.js`,
+            }, handoff);
+        }
+        catch (e) {
+            logger_1.Logger.error(`Failed to bundle JS for component "${id}" (${id}.js):`, e);
+            return data;
+        }
         data.js = js;
-        const compiled = yield fs_extra_1.default.readFile(path_1.default.resolve(outputPath, `${id}.js`), 'utf8');
-        data['jsCompiled'] = compiled;
+        if (yield fs_extra_1.default.pathExists(builtJsPath)) {
+            const compiled = yield fs_extra_1.default.readFile(builtJsPath, 'utf8');
+            data['jsCompiled'] = compiled;
+        }
+        else {
+            delete data['jsCompiled'];
+        }
     }
     catch (e) {
         logger_1.Logger.error(`JS build failed for component "${id}":`, e);
@@ -106,17 +125,24 @@ exports.buildComponentJs = buildComponentJs;
  *
  * @param handoff - The Handoff configuration object containing build settings
  * @returns A Promise that resolves when the build process is complete
- * @throws May throw an error if the build process fails
  */
 const buildMainJS = (handoff) => __awaiter(void 0, void 0, void 0, function* () {
     const outputPath = (0, component_1.getComponentOutputPath)(handoff);
     const runtimeConfig = (0, config_1.initRuntimeConfig)(handoff)[0];
     if (runtimeConfig && runtimeConfig.entries.js && fs_extra_1.default.existsSync(path_1.default.resolve(runtimeConfig.entries.js))) {
-        yield buildJsBundle({
-            entry: runtimeConfig.entries.js,
-            outputPath,
-            outputFilename: 'main.js',
-        }, handoff);
+        logger_1.Logger.info(`Building script for global entry (${exports.MAIN_COMPONENT_JS_FILE})…`);
+        const startedAt = Date.now();
+        try {
+            yield buildJsBundle({
+                entry: runtimeConfig.entries.js,
+                outputPath,
+                outputFilename: exports.MAIN_COMPONENT_JS_FILE,
+            }, handoff);
+            logger_1.Logger.info(`Finished building script for global entry (${exports.MAIN_COMPONENT_JS_FILE}) in ${(0, duration_1.formatDurationMs)(Date.now() - startedAt)}`);
+        }
+        catch (e) {
+            logger_1.Logger.error(`Failed to build global script (${exports.MAIN_COMPONENT_JS_FILE}):`, e);
+        }
     }
 });
 exports.buildMainJS = buildMainJS;

package/dist/transformers/preview/component/summary.d.ts

@@ -0,0 +1,6 @@
+import Handoff from '../../../index';
+import { ComponentListObject } from '../types';
+declare const writeComponentSummaryAPI: (handoff: Handoff, componentData: ComponentListObject[]) => Promise<void>;
+export declare const updateComponentSummaryApi: (handoff: Handoff, componentData: ComponentListObject[], isFullRebuild?: boolean) => Promise<void>;
+export declare const removeComponentFromSummaryApi: (handoff: Handoff, id: string) => Promise<void>;
+export default writeComponentSummaryAPI;

package/dist/transformers/preview/component/summary.js

@@ -0,0 +1,55 @@
+"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.removeComponentFromSummaryApi = exports.updateComponentSummaryApi = void 0;
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const path_1 = __importDefault(require("path"));
+const previews_1 = require("./previews");
+const api_1 = require("./api");
+const getComponentSummaryPath = (handoff) => path_1.default.resolve((0, api_1.getAPIPath)(handoff), 'components.json');
+const writeComponentSummaryAPI = (handoff, componentData) => __awaiter(void 0, void 0, void 0, function* () {
+    componentData.sort((a, b) => a.title.localeCompare(b.title));
+    yield fs_extra_1.default.writeFile(getComponentSummaryPath(handoff), JSON.stringify(componentData, null, 2));
+});
+const readExistingComponentSummaryApi = (handoff) => __awaiter(void 0, void 0, void 0, function* () {
+    const apiPath = getComponentSummaryPath(handoff);
+    if (!fs_extra_1.default.existsSync(apiPath)) {
+        return [];
+    }
+    try {
+        const existing = yield fs_extra_1.default.readFile(apiPath, 'utf8');
+        return JSON.parse(existing).map((component) => (Object.assign(Object.assign({}, component), { previews: (0, previews_1.getDocumentedPreviews)(component.previews) })));
+    }
+    catch (_a) {
+        return [];
+    }
+});
+const updateComponentSummaryApi = (handoff_1, componentData_1, ...args_1) => __awaiter(void 0, [handoff_1, componentData_1, ...args_1], void 0, function* (handoff, componentData, isFullRebuild = false) {
+    if (isFullRebuild) {
+        yield writeComponentSummaryAPI(handoff, componentData);
+        return;
+    }
+    const existingData = yield readExistingComponentSummaryApi(handoff);
+    const incomingIds = new Set(componentData.map((c) => c.id));
+    const merged = [...componentData, ...existingData.filter((c) => !incomingIds.has(c.id))];
+    yield writeComponentSummaryAPI(handoff, merged);
+});
+exports.updateComponentSummaryApi = updateComponentSummaryApi;
+const removeComponentFromSummaryApi = (handoff, id) => __awaiter(void 0, void 0, void 0, function* () {
+    const existingData = yield readExistingComponentSummaryApi(handoff);
+    const filtered = existingData.filter((component) => component.id !== id);
+    yield writeComponentSummaryAPI(handoff, filtered);
+});
+exports.removeComponentFromSummaryApi = removeComponentFromSummaryApi;
+exports.default = writeComponentSummaryAPI;

package/dist/transformers/preview/component.js

@@ -1,27 +1,4 @@
 "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) {
@@ -38,7 +15,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.getComponentOutputPath = exports.SlotType = void 0;
 exports.componentTransformer = componentTransformer;
 const path_1 = __importDefault(require("path"));
-const api_1 = __importStar(require("./component/api"));
+const api_1 = require("./component/api");
+const summary_1 = __importDefault(require("./component/summary"));
 const builder_1 = __importDefault(require("./component/builder"));
 const css_1 = require("./component/css");
 const javascript_1 = require("./component/javascript");
@@ -66,7 +44,7 @@ exports.getComponentOutputPath = getComponentOutputPath;
 function componentTransformer(handoff) {
     return __awaiter(this, void 0, void 0, function* () {
         const componentData = yield (0, builder_1.default)(handoff);
-        yield (0, api_1.default)(handoff, componentData);
+        yield (0, summary_1.default)(handoff, componentData);
         yield (0, javascript_1.buildMainJS)(handoff);
         yield (0, css_1.buildMainCss)(handoff);
     });

package/dist/transformers/preview/pattern/api.d.ts

@@ -4,4 +4,8 @@ export declare const getPatternAPIPath: (handoff: Handoff) => string;
 export declare const writePatternApi: (id: string, pattern: PatternObject, handoff: Handoff) => Promise<void>;
 export declare const writePatternHtml: (id: string, html: string, handoff: Handoff) => Promise<void>;
 export declare const writePatternSummaryApi: (handoff: Handoff, patterns: PatternListObject[]) => Promise<void>;
+/**
+ * Reads the pattern list summary when present (used for partial pattern rebuilds).
+ */
+export declare const readPatternSummaryApi: (handoff: Handoff) => Promise<PatternListObject[] | null>;
 export declare const syncPatternArtifacts: (handoff: Handoff, validIds: Iterable<string>) => Promise<void>;

package/dist/transformers/preview/pattern/api.js

@@ -12,7 +12,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.syncPatternArtifacts = exports.writePatternSummaryApi = exports.writePatternHtml = exports.writePatternApi = exports.getPatternAPIPath = void 0;
+exports.syncPatternArtifacts = exports.readPatternSummaryApi = exports.writePatternSummaryApi = exports.writePatternHtml = exports.writePatternApi = exports.getPatternAPIPath = void 0;
 const fs_extra_1 = __importDefault(require("fs-extra"));
 const path_1 = __importDefault(require("path"));
 const getPatternAPIPath = (handoff) => {
@@ -44,6 +44,24 @@ const writePatternSummaryApi = (handoff, patterns) => __awaiter(void 0, void 0,
     yield fs_extra_1.default.writeFile(path_1.default.resolve(apiPath, 'patterns.json'), JSON.stringify(patterns, null, 2));
 });
 exports.writePatternSummaryApi = writePatternSummaryApi;
+/**
+ * Reads the pattern list summary when present (used for partial pattern rebuilds).
+ */
+const readPatternSummaryApi = (handoff) => __awaiter(void 0, void 0, void 0, function* () {
+    const summaryPath = path_1.default.resolve(handoff.workingPath, 'public/api/patterns.json');
+    if (!fs_extra_1.default.existsSync(summaryPath)) {
+        return null;
+    }
+    try {
+        const raw = yield fs_extra_1.default.readFile(summaryPath, 'utf8');
+        const parsed = JSON.parse(raw);
+        return Array.isArray(parsed) ? parsed : null;
+    }
+    catch (_a) {
+        return null;
+    }
+});
+exports.readPatternSummaryApi = readPatternSummaryApi;
 const syncPatternArtifacts = (handoff, validIds) => __awaiter(void 0, void 0, void 0, function* () {
     const validIdSet = new Set(validIds);
     const patternPath = (0, exports.getPatternAPIPath)(handoff);

package/dist/transformers/preview/pattern/builder.d.ts

@@ -1,9 +1,17 @@
 import Handoff from '../../../index';
 import { PatternListObject } from '../types';
+export type ProcessPatternsOptions = {
+    /** When set, only these pattern ids are recomposed; others keep existing artifacts. */
+    onlyPatternIds?: Set<string>;
+};
+/**
+ * Returns pattern ids whose declarations reference any of the given component ids.
+ */
+export declare const getPatternIdsReferencingComponents: (handoff: Handoff, componentIds: string[]) => string[];
 /**
  * Process all pattern declarations and compose their HTML from pre-built
  * component preview files. This function must run AFTER buildComponents
  * so that all component preview HTML files already exist on disk.
  */
-export declare function processPatterns(handoff: Handoff): Promise<PatternListObject[]>;
+export declare function processPatterns(handoff: Handoff, options?: ProcessPatternsOptions): Promise<PatternListObject[]>;
 export default processPatterns;