handoff-app 1.2.0-1 → 1.2.0-2

package/dist/app-builder/paths.js

@@ -41,6 +41,15 @@ const getAppPath = (handoff) => {
     return path_1.default.resolve(handoff.modulePath, '.handoff', `${handoff.getProjectId()}`);
 };
 exports.getAppPath = getAppPath;
+const mirrorDirectory = (sourcePath, destinationPath) => __awaiter(void 0, void 0, void 0, function* () {
+    if (!(yield fs_extra_1.default.pathExists(sourcePath))) {
+        yield fs_extra_1.default.remove(destinationPath);
+        return;
+    }
+    yield fs_extra_1.default.remove(destinationPath);
+    yield fs_extra_1.default.ensureDir(path_1.default.dirname(destinationPath));
+    yield fs_extra_1.default.copy(sourcePath, destinationPath, { overwrite: true });
+});
 /**
  * Copy the public dir from the working dir to the module dir.
  */
@@ -48,9 +57,17 @@ 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'), {
+        const destinationPublicPath = path_1.default.resolve(appPath, 'public');
+        const sourceApiPath = path_1.default.resolve(workingPublicPath, 'api');
+        const destinationApiPath = path_1.default.resolve(destinationPublicPath, 'api');
+        yield fs_extra_1.default.copy(workingPublicPath, destinationPublicPath, {
             overwrite: true,
+            filter: (file) => {
+                const relativePath = path_1.default.relative(workingPublicPath, file);
+                return relativePath !== 'api' && !relativePath.startsWith(`api${path_1.default.sep}`);
+            },
         });
+        yield mirrorDirectory(sourceApiPath, destinationApiPath);
     }
 });
 exports.syncPublicFiles = syncPublicFiles;

package/dist/cli.js

@@ -19,7 +19,7 @@ class HandoffCliError extends Error {
  * Show the help message
  */
 const showVersion = () => {
-    return 'Handoff App - 1.2.0-1';
+    return 'Handoff App - 1.2.0-2';
 };
 /**
  * Define a CLI error

package/dist/transformers/plugins/csf-render.js

@@ -22,6 +22,7 @@ const react_element_to_jsx_string_1 = __importDefault(require("react-element-to-
 const logger_1 = require("../../utils/logger");
 const docgen_1 = require("../docgen");
 const component_1 = require("../preview/component");
+const css_1 = require("../preview/component/css");
 const html_1 = require("../utils/html");
 const module_1 = require("../utils/module");
 const schema_1 = require("../utils/schema");
@@ -240,7 +241,7 @@ function createHtmlDocument(componentId, previewTitle, renderedHtml) {
 <html lang="en">
   <head>
     <meta charset="UTF-8" />
-    <link rel="stylesheet" href="${(_a = process.env.HANDOFF_APP_BASE_PATH) !== null && _a !== void 0 ? _a : ''}/api/component/main.css" />
+    <link rel="stylesheet" href="${(_a = process.env.HANDOFF_APP_BASE_PATH) !== null && _a !== void 0 ? _a : ''}/api/component/${css_1.MAIN_COMPONENT_CSS_FILE}" />
     <link rel="stylesheet" href="${(_b = process.env.HANDOFF_APP_BASE_PATH) !== null && _b !== void 0 ? _b : ''}/api/component/${componentId}.css" />
     <link rel="stylesheet" href="${(_c = process.env.HANDOFF_APP_BASE_PATH) !== null && _c !== void 0 ? _c : ''}/assets/css/preview.css" />
     <title>${previewTitle}</title>

package/dist/transformers/plugins/ssr-render.js

@@ -21,6 +21,7 @@ const server_1 = __importDefault(require("react-dom/server"));
 const vite_1 = require("vite");
 const logger_1 = require("../../utils/logger");
 const docgen_1 = require("../docgen");
+const css_1 = require("../preview/component/css");
 const build_1 = require("../utils/build");
 const html_1 = require("../utils/html");
 const module_1 = require("../utils/module");
@@ -117,7 +118,7 @@ function generateHtmlDocument(componentId, previewTitle, renderedHtml, clientJs,
 <html lang="en">
   <head>
     <meta charset="UTF-8" />
-    <link rel="stylesheet" href="${(_a = process.env.HANDOFF_APP_BASE_PATH) !== null && _a !== void 0 ? _a : ''}/api/component/main.css" />
+    <link rel="stylesheet" href="${(_a = process.env.HANDOFF_APP_BASE_PATH) !== null && _a !== void 0 ? _a : ''}/api/component/${css_1.MAIN_COMPONENT_CSS_FILE}" />
     <link rel="stylesheet" href="${(_b = process.env.HANDOFF_APP_BASE_PATH) !== null && _b !== void 0 ? _b : ''}/api/component/${componentId}.css" />
     <link rel="stylesheet" href="${(_c = process.env.HANDOFF_APP_BASE_PATH) !== null && _c !== void 0 ? _c : ''}/assets/css/preview.css" />
     <script id="${PLUGIN_CONSTANTS.PROPS_SCRIPT_ID}" type="application/json">${JSON.stringify(props)}</script>

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

@@ -1,19 +1,8 @@
 import Handoff from '../../../index';
 import { ComponentListObject, TransformComponentTokensResult } from '../types';
+export declare const sanitizeComponentApiData: (component: TransformComponentTokensResult) => TransformComponentTokensResult;
 export declare const getAPIPath: (handoff: Handoff) => string;
-/**
- * Build the preview API from the component data
- * @param handoff
- * @param componentData
- */
-declare const writeComponentSummaryAPI: (handoff: Handoff, componentData: ComponentListObject[]) => Promise<void>;
 export declare const writeComponentApi: (id: string, component: TransformComponentTokensResult, handoff: Handoff, preserveKeys?: string[]) => Promise<void>;
-/**
- * Update the main component summary API with the new component data
- * @param handoff
- * @param componentData
- */
-export declare const updateComponentSummaryApi: (handoff: Handoff, componentData: ComponentListObject[], isFullRebuild?: boolean) => Promise<void>;
 /**
  * Read the component API data
  * @param handoff
@@ -28,4 +17,4 @@ export declare const readComponentApi: (handoff: Handoff, id: string) => Promise
  * @returns The component summary or null if not found
  */
 export declare const readComponentMetadataApi: (handoff: Handoff, id: string) => Promise<ComponentListObject | null>;
-export default writeComponentSummaryAPI;
+export default writeComponentApi;

package/dist/transformers/preview/component/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.readComponentMetadataApi = exports.readComponentApi = exports.updateComponentSummaryApi = exports.writeComponentApi = exports.getAPIPath = void 0;
+exports.readComponentMetadataApi = exports.readComponentApi = exports.writeComponentApi = exports.getAPIPath = exports.sanitizeComponentApiData = void 0;
 const fs_extra_1 = __importDefault(require("fs-extra"));
 const path_1 = __importDefault(require("path"));
 const previews_1 = require("./previews");
@@ -23,6 +23,7 @@ const sanitizeComponentApiData = (component) => {
     delete sanitized.internalPatternPreviews;
     return sanitized;
 };
+exports.sanitizeComponentApiData = sanitizeComponentApiData;
 /**
  * Merges values from a source object into a target object, returning a new object.
  * For each key present in either object:
@@ -62,28 +63,19 @@ const getAPIPath = (handoff) => {
     return apiPath;
 };
 exports.getAPIPath = getAPIPath;
-/**
- * Build the preview API from the component data
- * @param handoff
- * @param componentData
- */
-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(path_1.default.resolve((0, exports.getAPIPath)(handoff), 'components.json'), JSON.stringify(componentData, null, 2));
-});
 const writeComponentApi = (id_1, component_1, handoff_1, ...args_1) => __awaiter(void 0, [id_1, component_1, handoff_1, ...args_1], void 0, function* (id, component, handoff, preserveKeys = []) {
     const outputDirPath = path_1.default.resolve((0, exports.getAPIPath)(handoff), 'component');
     const outputFilePath = path_1.default.resolve(outputDirPath, `${id}.json`);
-    const sanitizedComponent = sanitizeComponentApiData(component);
+    const sanitizedComponent = (0, exports.sanitizeComponentApiData)(component);
     if (fs_extra_1.default.existsSync(outputFilePath)) {
         const existingJson = yield fs_extra_1.default.readFile(outputFilePath, 'utf8');
         if (existingJson) {
             try {
-                const existingData = sanitizeComponentApiData(JSON.parse(existingJson));
+                const existingData = (0, exports.sanitizeComponentApiData)(JSON.parse(existingJson));
                 // Special case: always allow page to be cleared when undefined
                 // This handles the case where page slices are removed
                 const finalPreserveKeys = sanitizedComponent.page === undefined ? preserveKeys.filter((key) => key !== 'page') : preserveKeys;
-                const mergedData = sanitizeComponentApiData(updateObject(existingData, sanitizedComponent, finalPreserveKeys));
+                const mergedData = (0, exports.sanitizeComponentApiData)(updateObject(existingData, sanitizedComponent, finalPreserveKeys));
                 yield fs_extra_1.default.writeFile(outputFilePath, JSON.stringify(mergedData, null, 2));
                 return;
             }
@@ -98,37 +90,6 @@ const writeComponentApi = (id_1, component_1, handoff_1, ...args_1) => __awaiter
     yield fs_extra_1.default.writeFile(outputFilePath, JSON.stringify(sanitizedComponent, null, 2));
 });
 exports.writeComponentApi = writeComponentApi;
-/**
- * Update the main component summary API with the new component data
- * @param handoff
- * @param componentData
- */
-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) {
-        // Full rebuild: replace the entire file
-        yield writeComponentSummaryAPI(handoff, componentData);
-        return;
-    }
-    // Partial update: merge with existing data
-    const apiPath = path_1.default.resolve((0, exports.getAPIPath)(handoff), 'components.json');
-    let existingData = [];
-    if (fs_extra_1.default.existsSync(apiPath)) {
-        try {
-            const existing = yield fs_extra_1.default.readFile(apiPath, 'utf8');
-            existingData = JSON.parse(existing).map((component) => (Object.assign(Object.assign({}, component), { previews: (0, previews_1.getDocumentedPreviews)(component.previews) })));
-        }
-        catch (_a) {
-            // Corrupt or missing JSON — treat as empty
-            existingData = [];
-        }
-    }
-    // Replace existing entries with same ID
-    const incomingIds = new Set(componentData.map((c) => c.id));
-    const merged = [...componentData, ...existingData.filter((c) => !incomingIds.has(c.id))];
-    // Always write the file (even if merged is empty)
-    yield writeComponentSummaryAPI(handoff, merged);
-});
-exports.updateComponentSummaryApi = updateComponentSummaryApi;
 /**
  * Read the component API data
  * @param handoff
@@ -141,7 +102,7 @@ const readComponentApi = (handoff, id) => __awaiter(void 0, void 0, void 0, func
         try {
             const existingJson = yield fs_extra_1.default.readFile(outputFilePath, 'utf8');
             if (existingJson) {
-                return sanitizeComponentApiData(JSON.parse(existingJson));
+                return (0, exports.sanitizeComponentApiData)(JSON.parse(existingJson));
             }
         }
         catch (_) {
@@ -180,4 +141,4 @@ const readComponentMetadataApi = (handoff, id) => __awaiter(void 0, void 0, void
     };
 });
 exports.readComponentMetadataApi = readComponentMetadataApi;
-exports.default = writeComponentSummaryAPI;
+exports.default = exports.writeComponentApi;

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

@@ -0,0 +1,4 @@
+import Handoff from '../../../index';
+export declare const getComponentApiPath: (handoff: Handoff) => string;
+export declare const removeComponentApi: (handoff: Handoff, id: string) => Promise<void>;
+export declare const syncComponentArtifacts: (handoff: Handoff) => Promise<void>;

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

@@ -32,7 +32,9 @@ 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"));
@@ -153,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;
@@ -367,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,7 +12,7 @@ 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");
@@ -22,6 +22,8 @@ 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
  *
@@ -91,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') {
@@ -124,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;
@@ -134,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) {
@@ -156,7 +170,7 @@ 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.info(`Building styles for global entry (main.css)…`);
+            logger_1.Logger.info(`Building styles for global entry (${exports.MAIN_COMPONENT_CSS_FILE})…`);
             const startedAt = Date.now();
             try {
                 const loadPaths = [
@@ -170,11 +184,11 @@ 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 (main.css) in ${(0, duration_1.formatDurationMs)(Date.now() - startedAt)}`);
+                logger_1.Logger.info(`Finished building styles for global entry (${exports.MAIN_COMPONENT_CSS_FILE}) in ${(0, duration_1.formatDurationMs)(Date.now() - startedAt)}`);
             }
             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,

package/dist/transformers/preview/component/javascript.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.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");
@@ -21,6 +21,7 @@ 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
  *
@@ -75,11 +76,20 @@ 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');
         try {
             yield buildJsBundle({
@@ -93,8 +103,13 @@ const buildComponentJs = (data, handoff) => __awaiter(void 0, void 0, void 0, fu
             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);
@@ -115,18 +130,18 @@ 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))) {
-        logger_1.Logger.info(`Building script for global entry (main.js)…`);
+        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: 'main.js',
+                outputFilename: exports.MAIN_COMPONENT_JS_FILE,
             }, handoff);
-            logger_1.Logger.info(`Finished building script for global entry (main.js) in ${(0, duration_1.formatDurationMs)(Date.now() - startedAt)}`);
+            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 (main.js):`, e);
+            logger_1.Logger.error(`Failed to build global script (${exports.MAIN_COMPONENT_JS_FILE}):`, e);
         }
     }
 });

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "handoff-app",
-  "version": "1.2.0-1",
+  "version": "1.2.0-2",
   "description": "Automated documentation toolchain for building client side documentation from figma",
   "author ": {
     "name": "Convertiv",

package/src/app-builder/paths.ts

@@ -30,6 +30,17 @@ export const getAppPath = (handoff: Handoff): string => {
   return path.resolve(handoff.modulePath, '.handoff', `${handoff.getProjectId()}`);
 };
 
+const mirrorDirectory = async (sourcePath: string, destinationPath: string): Promise<void> => {
+  if (!(await fs.pathExists(sourcePath))) {
+    await fs.remove(destinationPath);
+    return;
+  }
+
+  await fs.remove(destinationPath);
+  await fs.ensureDir(path.dirname(destinationPath));
+  await fs.copy(sourcePath, destinationPath, { overwrite: true });
+};
+
 /**
  * Copy the public dir from the working dir to the module dir.
  */
@@ -37,8 +48,18 @@ export const syncPublicFiles = async (handoff: Handoff): Promise<void> => {
   const appPath = getAppPath(handoff);
   const workingPublicPath = getWorkingPublicPath(handoff);
   if (workingPublicPath) {
-    await fs.copy(workingPublicPath, path.resolve(appPath, 'public'), {
+    const destinationPublicPath = path.resolve(appPath, 'public');
+    const sourceApiPath = path.resolve(workingPublicPath, 'api');
+    const destinationApiPath = path.resolve(destinationPublicPath, 'api');
+
+    await fs.copy(workingPublicPath, destinationPublicPath, {
       overwrite: true,
+      filter: (file) => {
+        const relativePath = path.relative(workingPublicPath, file);
+        return relativePath !== 'api' && !relativePath.startsWith(`api${path.sep}`);
+      },
     });
+
+    await mirrorDirectory(sourceApiPath, destinationApiPath);
   }
 };

package/src/cli.ts

@@ -19,7 +19,7 @@ class HandoffCliError extends Error {
  * Show the help message
  */
 const showVersion = () => {
-  return 'Handoff App - 1.2.0-1';
+  return 'Handoff App - 1.2.0-2';
 };
 
 /**

package/src/transformers/plugins/csf-render.ts

@@ -10,6 +10,7 @@ import Handoff from '../..';
 import { Logger } from '../../utils/logger';
 import { generateDocsArtifact, getPropertiesForComponentFromDocs } from '../docgen';
 import { SlotMetadata, SlotType } from '../preview/component';
+import { MAIN_COMPONENT_CSS_FILE } from '../preview/component/css';
 import { TransformComponentTokensResult } from '../preview/types';
 import { formatHtml, trimPreview } from '../utils/html';
 import { buildAndEvaluateModule } from '../utils/module';
@@ -270,7 +271,7 @@ function createHtmlDocument(componentId: string, previewTitle: string, renderedH
 <html lang="en">
   <head>
     <meta charset="UTF-8" />
-    <link rel="stylesheet" href="${process.env.HANDOFF_APP_BASE_PATH ?? ''}/api/component/main.css" />
+    <link rel="stylesheet" href="${process.env.HANDOFF_APP_BASE_PATH ?? ''}/api/component/${MAIN_COMPONENT_CSS_FILE}" />
     <link rel="stylesheet" href="${process.env.HANDOFF_APP_BASE_PATH ?? ''}/api/component/${componentId}.css" />
     <link rel="stylesheet" href="${process.env.HANDOFF_APP_BASE_PATH ?? ''}/assets/css/preview.css" />
     <title>${previewTitle}</title>

package/src/transformers/plugins/ssr-render.ts

@@ -14,6 +14,7 @@ import {
     getPropertiesFromGeneratedDocs,
 } from '../docgen';
 import { SlotMetadata } from '../preview/component';
+import { MAIN_COMPONENT_CSS_FILE } from '../preview/component/css';
 import { TransformComponentTokensResult } from '../preview/types';
 import { DEFAULT_CLIENT_BUILD_CONFIG, createReactResolvePlugin } from '../utils/build';
 import { formatHtml, trimPreview } from '../utils/html';
@@ -124,7 +125,7 @@ function generateHtmlDocument(componentId: string, previewTitle: string, rendere
 <html lang="en">
   <head>
     <meta charset="UTF-8" />
-    <link rel="stylesheet" href="${process.env.HANDOFF_APP_BASE_PATH ?? ''}/api/component/main.css" />
+    <link rel="stylesheet" href="${process.env.HANDOFF_APP_BASE_PATH ?? ''}/api/component/${MAIN_COMPONENT_CSS_FILE}" />
     <link rel="stylesheet" href="${process.env.HANDOFF_APP_BASE_PATH ?? ''}/api/component/${componentId}.css" />
     <link rel="stylesheet" href="${process.env.HANDOFF_APP_BASE_PATH ?? ''}/assets/css/preview.css" />
     <script id="${PLUGIN_CONSTANTS.PROPS_SCRIPT_ID}" type="application/json">${JSON.stringify(props)}</script>

package/src/transformers/preview/component/api.ts

@@ -4,7 +4,7 @@ import Handoff from '../../../index';
 import { ComponentListObject, TransformComponentTokensResult } from '../types';
 import { getDocumentedPreviews } from './previews';
 
-const sanitizeComponentApiData = (
+export const sanitizeComponentApiData = (
   component: TransformComponentTokensResult
 ): TransformComponentTokensResult => {
   if (!component) return component;
@@ -64,16 +64,6 @@ export const getAPIPath = (handoff: Handoff) => {
   return apiPath;
 };
 
-/**
- * Build the preview API from the component data
- * @param handoff
- * @param componentData
- */
-const writeComponentSummaryAPI = async (handoff: Handoff, componentData: ComponentListObject[]) => {
-  componentData.sort((a, b) => a.title.localeCompare(b.title));
-  await fs.writeFile(path.resolve(getAPIPath(handoff), 'components.json'), JSON.stringify(componentData, null, 2));
-};
-
 export const writeComponentApi = async (
   id: string,
   component: TransformComponentTokensResult,
@@ -110,43 +100,6 @@ export const writeComponentApi = async (
   await fs.writeFile(outputFilePath, JSON.stringify(sanitizedComponent, null, 2));
 };
 
-/**
- * Update the main component summary API with the new component data
- * @param handoff
- * @param componentData
- */
-export const updateComponentSummaryApi = async (handoff: Handoff, componentData: ComponentListObject[], isFullRebuild: boolean = false) => {
-  if (isFullRebuild) {
-    // Full rebuild: replace the entire file
-    await writeComponentSummaryAPI(handoff, componentData);
-    return;
-  }
-
-  // Partial update: merge with existing data
-  const apiPath = path.resolve(getAPIPath(handoff), 'components.json');
-  let existingData: ComponentListObject[] = [];
-
-  if (fs.existsSync(apiPath)) {
-    try {
-      const existing = await fs.readFile(apiPath, 'utf8');
-      existingData = (JSON.parse(existing) as ComponentListObject[]).map((component) => ({
-        ...component,
-        previews: getDocumentedPreviews(component.previews),
-      }));
-    } catch {
-      // Corrupt or missing JSON — treat as empty
-      existingData = [];
-    }
-  }
-
-  // Replace existing entries with same ID
-  const incomingIds = new Set(componentData.map((c) => c.id));
-  const merged = [...componentData, ...existingData.filter((c) => !incomingIds.has(c.id))];
-
-  // Always write the file (even if merged is empty)
-  await writeComponentSummaryAPI(handoff, merged);
-};
-
 /**
  * Read the component API data
  * @param handoff
@@ -198,5 +151,4 @@ export const readComponentMetadataApi = async (handoff: Handoff, id: string): Pr
     path: `/api/component/${id}.json`,
   };
 };
-
-export default writeComponentSummaryAPI;
+export default writeComponentApi;

package/src/transformers/preview/component/artifacts.ts

@@ -0,0 +1,131 @@
+import fs from 'fs-extra';
+import path from 'path';
+import Handoff from '../../../index';
+import { TransformComponentTokensResult } from '../types';
+import { getDocumentedPreviews } from './previews';
+import { getAPIPath, sanitizeComponentApiData } from './api';
+import { MAIN_COMPONENT_CSS_FILE, SHARED_COMPONENT_CSS_FILE } from './css';
+import { MAIN_COMPONENT_JS_FILE } from './javascript';
+
+const COMPONENT_JS_RESERVED_FILES = new Set([MAIN_COMPONENT_JS_FILE]);
+const COMPONENT_CSS_RESERVED_FILES = new Set([MAIN_COMPONENT_CSS_FILE, SHARED_COMPONENT_CSS_FILE]);
+
+export const getComponentApiPath = (handoff: Handoff) => path.resolve(getAPIPath(handoff), 'component');
+
+const getComponentPreviewKeys = async (handoff: Handoff, componentId: string): Promise<Set<string>> => {
+  const runtimeComponent = handoff.runtimeConfig?.entries?.components?.[componentId];
+  const previewKeys = new Set<string>();
+
+  const outputFilePath = path.resolve(getComponentApiPath(handoff), `${componentId}.json`);
+  if (fs.existsSync(outputFilePath)) {
+    try {
+      const existingJson = await fs.readFile(outputFilePath, 'utf8');
+      if (existingJson) {
+        const existingData = sanitizeComponentApiData(JSON.parse(existingJson) as TransformComponentTokensResult);
+        for (const previewKey of Object.keys(existingData?.previews || {})) {
+          previewKeys.add(previewKey);
+        }
+      }
+    } catch {
+      // Fall back to runtime config below.
+    }
+  }
+
+  for (const previewKey of Object.keys(getDocumentedPreviews(runtimeComponent?.previews) || {})) {
+    previewKeys.add(previewKey);
+  }
+
+  for (const previewKey of Object.keys(runtimeComponent?.internalPatternPreviews || {})) {
+    previewKeys.add(previewKey);
+  }
+
+  return previewKeys;
+};
+
+const getArtifactComponentId = (fileName: string, componentIds: Iterable<string>): string | null => {
+  let match: string | null = null;
+
+  for (const componentId of componentIds) {
+    if (!fileName.startsWith(`${componentId}-`)) continue;
+    if (!match || componentId.length > match.length) {
+      match = componentId;
+    }
+  }
+
+  return match;
+};
+
+export const removeComponentApi = async (handoff: Handoff, id: string): Promise<void> => {
+  const outputDirPath = getComponentApiPath(handoff);
+  const outputFilePath = path.resolve(outputDirPath, `${id}.json`);
+
+  if (await fs.pathExists(outputFilePath)) {
+    await fs.remove(outputFilePath);
+  }
+};
+
+export const syncComponentArtifacts = async (handoff: Handoff): Promise<void> => {
+  const componentPath = getComponentApiPath(handoff);
+  await fs.ensureDir(componentPath);
+
+  const runtimeComponents = handoff.runtimeConfig?.entries?.components ?? {};
+  const runtimeIds = Object.keys(runtimeComponents);
+  const entries = await fs.readdir(componentPath);
+
+  const discoveredArtifactIds = new Set<string>(runtimeIds);
+  for (const entry of entries) {
+    const parsed = path.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<string>();
+  for (const componentId of runtimeIds) {
+    validFiles.add(`${componentId}.json`);
+
+    if (await fs.pathExists(path.resolve(componentPath, `${componentId}.js`))) {
+      validFiles.add(`${componentId}.js`);
+    }
+
+    if (await fs.pathExists(path.resolve(componentPath, `${componentId}.css`))) {
+      validFiles.add(`${componentId}.css`);
+    }
+
+    const previewKeys = await 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.parse(entry);
+
+    if (parsed.ext === '.json' || parsed.ext === '.js' || parsed.ext === '.css') {
+      if (!validFiles.has(entry)) {
+        await fs.remove(path.resolve(componentPath, entry));
+      }
+      continue;
+    }
+
+    if (parsed.ext !== '.html') {
+      continue;
+    }
+
+    const ownerId = getArtifactComponentId(entry, discoveredArtifactIds);
+    if (!ownerId) {
+      continue;
+    }
+
+    if (!validFiles.has(entry)) {
+      await fs.remove(path.resolve(componentPath, entry));
+    }
+  }
+};

package/src/transformers/preview/component/builder.ts

@@ -18,8 +18,10 @@ import { formatDurationMs } from '../../../utils/duration';
 import { Logger } from '../../../utils/logger';
 import { ensureIds } from '../../utils/schema';
 import { ComponentListObject, ComponentType, OptionalPreviewRender, TransformComponentTokensResult } from '../types';
-import { readComponentApi, readComponentMetadataApi, updateComponentSummaryApi, writeComponentApi } from './api';
+import { readComponentApi, readComponentMetadataApi, writeComponentApi } from './api';
+import { removeComponentApi, syncComponentArtifacts } from './artifacts';
 import { getDocumentedPreviews } from './previews';
+import { removeComponentFromSummaryApi, updateComponentSummaryApi } from './summary';
 import buildComponentCss from './css';
 import buildPreviews from './html';
 import buildComponentJs from './javascript';
@@ -179,6 +181,13 @@ export async function processComponents(
   const runtimeComponents = handoff.runtimeConfig?.entries?.components ?? {};
   const allComponentIds = Object.keys(runtimeComponents);
 
+  if (id && !runtimeComponents[id]) {
+    await removeComponentApi(handoff, id);
+    await removeComponentFromSummaryApi(handoff, id);
+    await syncComponentArtifacts(handoff);
+    return [];
+  }
+
   // Determine which components need building based on cache (when enabled)
   let componentsToBuild: Set<string>;
   let cache: BuildCache | null = null;
@@ -425,6 +434,7 @@ export async function processComponents(
   // Always merge and write summary file, even if no components processed
   const isFullRebuild = !id;
   await updateComponentSummaryApi(handoff, result, isFullRebuild);
+  await syncComponentArtifacts(handoff);
 
   return result;
 }

package/src/transformers/preview/component/css.ts

@@ -10,6 +10,9 @@ import { getComponentOutputPath } from '../component';
 import { TransformComponentTokensResult } from '../types';
 const { pathToFileURL } = require('url');
 
+export const MAIN_COMPONENT_CSS_FILE = 'main.css';
+export const SHARED_COMPONENT_CSS_FILE = 'shared.css';
+
 /**
  * Builds a CSS bundle using Vite
  *
@@ -99,8 +102,16 @@ const buildCssBundle = async ({
 const buildComponentCss = async (data: TransformComponentTokensResult, handoff: Handoff) => {
   const id = data.id;
   Logger.debug(`buildComponentCss`, id);
+  const outputPath = getComponentOutputPath(handoff);
+  const builtCssPath = path.resolve(outputPath, `${id}.css`);
   const entry = data.entries?.scss;
+
   if (!entry) {
+    // Keep generated output aligned with the current component declaration.
+    await fs.remove(builtCssPath);
+    delete data['css'];
+    delete data['sass'];
+    delete data['sharedStyles'];
     return data;
   }
 
@@ -110,10 +121,12 @@ const buildComponentCss = async (data: TransformComponentTokensResult, handoff:
     return data;
   }
 
-  const outputPath = 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.
+      await fs.remove(builtCssPath);
+
       // Read the original source
       const sourceContent = await fs.readFile(entry, 'utf8');
       if (extension === '.scss') {
@@ -140,7 +153,6 @@ const buildComponentCss = async (data: TransformComponentTokensResult, handoff:
       });
 
       // Read the built CSS
-      const builtCssPath = path.resolve(outputPath, `${id}.css`);
       if (fs.existsSync(builtCssPath)) {
         const builtCss = await fs.readFile(builtCssPath, 'utf8');
         data['css'] = builtCss;
@@ -151,8 +163,11 @@ const buildComponentCss = async (data: TransformComponentTokensResult, handoff:
         if (splitCSS && splitCSS.length > 1) {
           data['css'] = splitCSS[1];
           data['sharedStyles'] = splitCSS[0];
-          await fs.writeFile(path.resolve(outputPath, 'shared.css'), data['sharedStyles']);
+          await fs.writeFile(path.resolve(outputPath, SHARED_COMPONENT_CSS_FILE), data['sharedStyles']);
         }
+      } else {
+        delete data['css'];
+        delete data['sharedStyles'];
       }
     }
   } catch (e) {
@@ -175,7 +190,7 @@ export const buildMainCss = async (handoff: Handoff): Promise<void> => {
     const entryPath = stat.isDirectory() ? path.resolve(runtimeConfig.entries.scss, 'main.scss') : runtimeConfig.entries.scss;
 
     if (entryPath === runtimeConfig.entries.scss || fs.existsSync(entryPath)) {
-      Logger.info(`Building styles for global entry (main.css)…`);
+      Logger.info(`Building styles for global entry (${MAIN_COMPONENT_CSS_FILE})…`);
       const startedAt = Date.now();
       try {
         const loadPaths = [
@@ -191,11 +206,11 @@ export const buildMainCss = async (handoff: Handoff): Promise<void> => {
         await buildCssBundle({
           entry: entryPath,
           outputPath,
-          outputFilename: 'main.css',
+          outputFilename: MAIN_COMPONENT_CSS_FILE,
           loadPaths,
           handoff,
         });
-        Logger.info(`Finished building styles for global entry (main.css) in ${formatDurationMs(Date.now() - startedAt)}`);
+        Logger.info(`Finished building styles for global entry (${MAIN_COMPONENT_CSS_FILE}) in ${formatDurationMs(Date.now() - startedAt)}`);
       } catch {
         // buildCssBundle already logs failure for the entry path
       }

package/src/transformers/preview/component/javascript.ts

@@ -9,6 +9,8 @@ import viteBaseConfig from '../../vite-config';
 import { getComponentOutputPath } from '../component';
 import { TransformComponentTokensResult } from '../types';
 
+export const MAIN_COMPONENT_JS_FILE = 'main.js';
+
 /**
  * Builds a JavaScript bundle using Vite
  *
@@ -78,12 +80,23 @@ const buildJsBundle = async (
  */
 export const buildComponentJs = async (data: TransformComponentTokensResult, handoff: Handoff): Promise<TransformComponentTokensResult> => {
   const id = data.id;
+  const outputPath = getComponentOutputPath(handoff);
+  const builtJsPath = path.resolve(outputPath, `${id}.js`);
   const entry = data.entries?.js;
-  if (!entry) return data;
 
-  const outputPath = getComponentOutputPath(handoff);
+  if (!entry) {
+    // Keep generated output aligned with the current component declaration.
+    await fs.remove(builtJsPath);
+    delete data.js;
+    delete data['jsCompiled'];
+    return data;
+  }
 
   try {
+    // Remove the previous artifact before rebuilding so a no-output build
+    // cannot accidentally preserve stale compiled JS.
+    await fs.remove(builtJsPath);
+
     const js = await fs.readFile(path.resolve(entry), 'utf8');
     try {
       await buildJsBundle(
@@ -100,8 +113,12 @@ export const buildComponentJs = async (data: TransformComponentTokensResult, han
     }
 
     data.js = js;
-    const compiled = await fs.readFile(path.resolve(outputPath, `${id}.js`), 'utf8');
-    data['jsCompiled'] = compiled;
+    if (await fs.pathExists(builtJsPath)) {
+      const compiled = await fs.readFile(builtJsPath, 'utf8');
+      data['jsCompiled'] = compiled;
+    } else {
+      delete data['jsCompiled'];
+    }
   } catch (e) {
     Logger.error(`JS build failed for component "${id}":`, e);
   }
@@ -123,20 +140,20 @@ export const buildMainJS = async (handoff: Handoff): Promise<void> => {
   const runtimeConfig = initRuntimeConfig(handoff)[0];
 
   if (runtimeConfig && runtimeConfig.entries.js && fs.existsSync(path.resolve(runtimeConfig.entries.js))) {
-    Logger.info(`Building script for global entry (main.js)…`);
+    Logger.info(`Building script for global entry (${MAIN_COMPONENT_JS_FILE})…`);
     const startedAt = Date.now();
     try {
       await buildJsBundle(
         {
           entry: runtimeConfig.entries.js,
           outputPath,
-          outputFilename: 'main.js',
+          outputFilename: MAIN_COMPONENT_JS_FILE,
         },
         handoff
       );
-      Logger.info(`Finished building script for global entry (main.js) in ${formatDurationMs(Date.now() - startedAt)}`);
+      Logger.info(`Finished building script for global entry (${MAIN_COMPONENT_JS_FILE}) in ${formatDurationMs(Date.now() - startedAt)}`);
     } catch (e) {
-      Logger.error(`Failed to build global script (main.js):`, e);
+      Logger.error(`Failed to build global script (${MAIN_COMPONENT_JS_FILE}):`, e);
     }
   }
 };

package/src/transformers/preview/component/summary.ts

@@ -0,0 +1,54 @@
+import fs from 'fs-extra';
+import path from 'path';
+import Handoff from '../../../index';
+import { ComponentListObject } from '../types';
+import { getDocumentedPreviews } from './previews';
+import { getAPIPath } from './api';
+
+const getComponentSummaryPath = (handoff: Handoff): string => path.resolve(getAPIPath(handoff), 'components.json');
+
+const writeComponentSummaryAPI = async (handoff: Handoff, componentData: ComponentListObject[]) => {
+  componentData.sort((a, b) => a.title.localeCompare(b.title));
+  await fs.writeFile(getComponentSummaryPath(handoff), JSON.stringify(componentData, null, 2));
+};
+
+const readExistingComponentSummaryApi = async (handoff: Handoff): Promise<ComponentListObject[]> => {
+  const apiPath = getComponentSummaryPath(handoff);
+  if (!fs.existsSync(apiPath)) {
+    return [];
+  }
+
+  try {
+    const existing = await fs.readFile(apiPath, 'utf8');
+    return (JSON.parse(existing) as ComponentListObject[]).map((component) => ({
+      ...component,
+      previews: getDocumentedPreviews(component.previews),
+    }));
+  } catch {
+    return [];
+  }
+};
+
+export const updateComponentSummaryApi = async (
+  handoff: Handoff,
+  componentData: ComponentListObject[],
+  isFullRebuild: boolean = false
+) => {
+  if (isFullRebuild) {
+    await writeComponentSummaryAPI(handoff, componentData);
+    return;
+  }
+
+  const existingData = await readExistingComponentSummaryApi(handoff);
+  const incomingIds = new Set(componentData.map((c) => c.id));
+  const merged = [...componentData, ...existingData.filter((c) => !incomingIds.has(c.id))];
+  await writeComponentSummaryAPI(handoff, merged);
+};
+
+export const removeComponentFromSummaryApi = async (handoff: Handoff, id: string): Promise<void> => {
+  const existingData = await readExistingComponentSummaryApi(handoff);
+  const filtered = existingData.filter((component) => component.id !== id);
+  await writeComponentSummaryAPI(handoff, filtered);
+};
+
+export default writeComponentSummaryAPI;

package/src/transformers/preview/component.ts

@@ -1,7 +1,8 @@
 import type { DocAnnotation, TypeNode } from 'handoff-docgen';
 import path from 'path';
 import Handoff from '../../index';
-import writeComponentSummaryAPI, { getAPIPath } from './component/api';
+import { getAPIPath } from './component/api';
+import writeComponentSummaryAPI from './component/summary';
 import processComponents from './component/builder';
 import { buildMainCss } from './component/css';
 import { buildMainJS } from './component/javascript';