handoff-app 1.2.0-1 → 1.2.0

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",
   "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';
 };
 
 /**

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';