handoff-app 1.2.0-0 → 1.2.0-2

package/src/pipeline/patterns.ts

@@ -1,10 +1,12 @@
 import Handoff from '..';
-import { processPatterns } from '../transformers/preview/pattern/builder';
+import { ProcessPatternsOptions, processPatterns } from '../transformers/preview/pattern/builder';
+
+export type { ProcessPatternsOptions };
 
 /**
  * Builds pattern previews by composing pre-built component preview HTML.
  * Must be called AFTER buildComponents.
  */
-export const buildPatterns = async (handoff: Handoff) => {
-  await processPatterns(handoff);
+export const buildPatterns = async (handoff: Handoff, options?: ProcessPatternsOptions) => {
+  await processPatterns(handoff, options);
 };

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

@@ -14,11 +14,14 @@ import {
   updateComponentCacheEntry,
 } from '../../../cache';
 import Handoff from '../../../index';
+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';
@@ -83,6 +86,44 @@ const getBuildPreviews = (data: TransformComponentTokensResult): { [key: string]
   };
 };
 
+/** Vite-backed segments in execution order; extend here if new steps are added. */
+const VITE_BUILD_SEGMENTS: {
+  key: keyof Pick<ComponentBuildPlan, 'js' | 'css' | 'previews'>;
+  label: string;
+}[] = [
+  { key: 'js', label: 'script' },
+  { key: 'css', label: 'styles' },
+  { key: 'previews', label: 'previews' },
+];
+
+const isFullViteComponentBuild = (plan: ComponentBuildPlan): boolean => plan.js && plan.css && plan.previews;
+
+const getActiveViteBuildLabels = (plan: ComponentBuildPlan): string[] =>
+  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: string[]): string => {
+  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: string, plan: ComponentBuildPlan): string => {
+  if (isFullViteComponentBuild(plan)) {
+    return `Building component "${componentId}"…`;
+  }
+  return `Building ${formatEnglishList(getActiveViteBuildLabels(plan))} for component "${componentId}"…`;
+};
+
+const viteBuildFinishMessage = (componentId: string, plan: ComponentBuildPlan, elapsedMs: number): string => {
+  const duration = 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.
  *
@@ -140,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;
@@ -193,11 +241,16 @@ export async function processComponents(
       pruneRemovedComponents(cache, allComponentIds);
     }
 
-    const skippedCount = allComponentIds.length - componentsToBuild.size;
-    if (skippedCount > 0) {
-      Logger.info(`Building ${componentsToBuild.size} of ${allComponentIds.length} components (${skippedCount} unchanged)`);
-    } else if (componentsToBuild.size > 0) {
-      Logger.info(`Building all ${componentsToBuild.size} components`);
+    const total = allComponentIds.length;
+    const toBuildCount = componentsToBuild.size;
+    const skippedCount = total - toBuildCount;
+
+    if (total > 0 && toBuildCount === 0) {
+      Logger.info(`All ${total} components unchanged; skipping build`);
+    } else if (skippedCount > 0 && toBuildCount > 0) {
+      Logger.info(`Building ${toBuildCount} of ${total} components (${skippedCount} unchanged)`);
+    } else if (toBuildCount > 0) {
+      Logger.info(`Building all ${toBuildCount} components`);
     } else {
       Logger.info('All components up to date, nothing to build');
     }
@@ -301,6 +354,13 @@ export async function processComponents(
     // 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.info(viteBuildStartMessage(runtimeComponentId, buildPlan));
+    }
+
     // Build JS if needed (new build, validation missing, or explicit segment request).
     if (buildPlan.js) {
       data = await buildComponentJs(data, handoff);
@@ -321,6 +381,11 @@ export async function processComponents(
       );
     }
 
+    if (runsViteBuildSteps) {
+      const elapsedMs = Date.now() - viteBuildStartedAtMs;
+      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.
@@ -369,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

@@ -3,12 +3,16 @@ import path from 'path';
 import { InlineConfig, build as viteBuild } from 'vite';
 import { initRuntimeConfig } from '../../../config';
 import Handoff from '../../../index';
+import { formatDurationMs } from '../../../utils/duration';
 import { Logger } from '../../../utils/logger';
 import viteBaseConfig from '../../vite-config';
 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
  *
@@ -98,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;
   }
 
@@ -109,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') {
@@ -139,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;
@@ -150,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) {
@@ -174,10 +190,9 @@ 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.success(`Building main CSS file...`);
-
+      Logger.info(`Building styles for global entry (${MAIN_COMPONENT_CSS_FILE})…`);
+      const startedAt = Date.now();
       try {
-        // Setup SASS load paths
         const loadPaths = [
           path.resolve(handoff.workingPath),
           path.resolve(handoff.workingPath, handoff.exportsDirectory, handoff.getProjectId()),
@@ -191,12 +206,13 @@ export const buildMainCss = async (handoff: Handoff): Promise<void> => {
         await buildCssBundle({
           entry: entryPath,
           outputPath,
-          outputFilename: 'main.css',
+          outputFilename: MAIN_COMPONENT_CSS_FILE,
           loadPaths,
           handoff,
         });
-      } catch (e) {
-        Logger.error(`Failed to build main CSS:`, e);
+        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

@@ -3,11 +3,14 @@ import path from 'path';
 import { InlineConfig, build as viteBuild } from 'vite';
 import { initRuntimeConfig } from '../../../config';
 import Handoff from '../../../index';
+import { formatDurationMs } from '../../../utils/duration';
 import { Logger } from '../../../utils/logger';
 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
  *
@@ -54,8 +57,6 @@ const buildJsBundle = async (
     }
 
     await viteBuild(viteConfig);
-  } catch (e) {
-    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
@@ -79,25 +80,45 @@ 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');
-    await buildJsBundle(
-      {
-        entry,
-        outputPath,
-        outputFilename: `${id}.js`,
-      },
-      handoff
-    );
+    try {
+      await buildJsBundle(
+        {
+          entry,
+          outputPath,
+          outputFilename: `${id}.js`,
+        },
+        handoff
+      );
+    } catch (e) {
+      Logger.error(`Failed to bundle JS for component "${id}" (${id}.js):`, e);
+      return data;
+    }
 
     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);
   }
@@ -113,21 +134,27 @@ export const buildComponentJs = async (data: TransformComponentTokensResult, han
  *
  * @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 const buildMainJS = async (handoff: Handoff): Promise<void> => {
   const outputPath = getComponentOutputPath(handoff);
   const runtimeConfig = initRuntimeConfig(handoff)[0];
 
   if (runtimeConfig && runtimeConfig.entries.js && fs.existsSync(path.resolve(runtimeConfig.entries.js))) {
-    await buildJsBundle(
-      {
-        entry: runtimeConfig.entries.js,
-        outputPath,
-        outputFilename: 'main.js',
-      },
-      handoff
-    );
+    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_COMPONENT_JS_FILE,
+        },
+        handoff
+      );
+      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_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';