handoff-app 1.2.0-1 → 1.2.0

package/Changelog.md

@@ -6,6 +6,71 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to
 [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.2.0] - 2026-04-03
+
+This release introduces support for patterns and significantly
+modernizes the configuration and declaration workflow. It expands Handoff from
+documenting individual components to documenting larger design-system
+compositions, while also improving TypeScript support, preview usability, and
+overall build and development reliability.
+
+### Patterns
+
+* Added support for design system patterns as a new documentation
+  layer above individual components.
+* Patterns support composing multiple component previews into a single page.
+* Pattern definitions can reference existing named component previews or
+  provide inline args for custom pattern-specific compositions.
+* Added support for `entries.patterns`, allowing projects to register composed
+  design-system patterns alongside components.
+* Added pattern summary and detail artifacts so patterns behave as first-class
+  generated output alongside components.
+
+### Typed Config and Declaration Workflow
+
+* Added support for typed TypeScript and JavaScript config and declaration
+  files across the project workflow.
+* Established TypeScript-based config and declaration files as the preferred
+  convention, while continuing to support JavaScript, CJS, and JSON where
+  applicable.
+* Added clear config resolution precedence when multiple root config files are
+  present.
+* Introduced the `.handoff.ts` and `.handoff.js` declaration convention for
+  components and patterns.
+* Introduced structured helper APIs including `defineConfig`,
+  `defineReactComponent`, `defineHandlebarsComponent`,
+  `defineCsfComponent`, and `definePattern`.
+* Updated runtime loading and normalization so typed declarations and modern
+  config shapes work consistently across the pipeline.
+* Updated scaffolding and CLI flows to support both TypeScript and JavaScript
+  project setup.
+* Updated generated examples and component scaffolds to follow the new
+  `.handoff.*` declaration convention.
+
+### Usage Snippets and Preview Improvements
+
+* Added usage snippets as a new documentation feature, with output that
+  reflects the currently selected preview variant.
+* Expanded CSF preview handling to produce more useful implementation examples
+  for React and Storybook-style components.
+* Improved story and preview resolution so generated documentation is more
+  actionable for engineers consuming the design system.
+* Enhanced code display behavior to better support usage-oriented
+  documentation rather than only static rendered output.
+
+### General Improvements
+
+* Improved incremental build and watch behavior so changes trigger more
+  selective and reliable rebuilds.
+* Added better cleanup of stale generated artifacts to keep component and
+  pattern output in sync as files change or are removed.
+* Improved summary artifact maintenance during rebuilds so generated API output
+  stays aligned with the current source of truth.
+* Enhanced logging with clearer scoped output across Handoff, Vite, and Next.js
+  processes.
+* Improved child-process logging and development server reporting to make local
+  debugging and build visibility better.
+
 ## \[1.1.3] - 2026-03-27
 
 This release reworks the markdown page rendering system with four improvements:

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