handoff-app 2.0.0-5 → 2.0.0-7

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

@@ -17,11 +17,21 @@ const fs_extra_1 = __importDefault(require("fs-extra"));
 const path_1 = __importDefault(require("path"));
 const url_1 = require("../../../artifacts/url");
 const previews_1 = require("./previews");
+/**
+ * Strip the fields that must not reach the written artifact.
+ *
+ * The docs API serves this artifact publicly, and publish uploads it verbatim. An absolute path in
+ * the artifact exposes the filesystem layout of the build machine, so this drops the workspace
+ * locations `path` and `entries`. The build takes those locations from the runtime config, and
+ * publish remaps `entries` onto the registry record.
+ */
 const sanitizeComponentApiData = (component) => {
     if (!component)
         return component;
     const sanitized = Object.assign(Object.assign({}, component), { previews: (0, previews_1.getDocumentedPreviews)(component.previews) });
     delete sanitized.internalPatternPreviews;
+    delete sanitized.entries;
+    delete sanitized.path;
     return sanitized;
 };
 exports.sanitizeComponentApiData = sanitizeComponentApiData;
@@ -126,21 +136,7 @@ const readComponentMetadataApi = (handoff, id) => __awaiter(void 0, void 0, void
         return null;
     }
     // Construct the summary from the full component data
-    return {
-        id,
-        title: componentData.title,
-        description: componentData.description,
-        type: componentData.type,
-        group: componentData.group,
-        image: componentData.image ? componentData.image : '',
-        figma: componentData.figma ? componentData.figma : '',
-        figmaComponentId: componentData.figmaComponentId,
-        categories: componentData.categories ? componentData.categories : [],
-        tags: componentData.tags ? componentData.tags : [],
-        properties: componentData.properties,
-        previews: (0, previews_1.getDocumentedPreviews)(componentData.previews),
-        path: (0, url_1.buildComponentDetailUrl)(id, (_a = process.env.HANDOFF_APP_BASE_PATH) !== null && _a !== void 0 ? _a : ''),
-    };
+    return Object.assign(Object.assign({ id, title: componentData.title, description: componentData.description, type: componentData.type, group: componentData.group, image: componentData.image ? componentData.image : '', figma: componentData.figma ? componentData.figma : '', figmaComponentId: componentData.figmaComponentId, categories: componentData.categories ? componentData.categories : [], tags: componentData.tags ? componentData.tags : [], properties: componentData.properties, previews: (0, previews_1.getDocumentedPreviews)(componentData.previews), path: (0, url_1.buildComponentDetailUrl)(id, (_a = process.env.HANDOFF_APP_BASE_PATH) !== null && _a !== void 0 ? _a : '') }, (componentData.renderer ? { renderer: componentData.renderer } : {})), (componentData.sourceFormat ? { sourceFormat: componentData.sourceFormat } : {}));
 });
 exports.readComponentMetadataApi = readComponentMetadataApi;
 exports.default = exports.writeComponentApi;

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

@@ -1,4 +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>;
+export declare const syncComponentArtifacts: (handoff: Handoff, removedIds?: readonly string[]) => Promise<void>;

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

@@ -26,8 +26,8 @@ const CLIENT_ARTIFACT_SUFFIX = '.client.js';
 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];
+    var _a;
+    const runtimeComponent = (_a = handoff.runtimeConfig) === null || _a === void 0 ? void 0 : _a.entities.components[componentId];
     const previewKeys = new Set();
     const outputFilePath = path_1.default.resolve((0, exports.getComponentApiPath)(handoff), `${componentId}.json`);
     if (fs_extra_1.default.existsSync(outputFilePath)) {
@@ -40,7 +40,7 @@ const getComponentPreviewKeys = (handoff, componentId) => __awaiter(void 0, void
                 }
             }
         }
-        catch (_d) {
+        catch (_b) {
             // Fall back to runtime config below.
         }
     }
@@ -71,14 +71,18 @@ const removeComponentApi = (handoff, id) => __awaiter(void 0, void 0, void 0, fu
     }
 });
 exports.removeComponentApi = removeComponentApi;
-const syncComponentArtifacts = (handoff) => __awaiter(void 0, void 0, void 0, function* () {
-    var _a, _b, _c;
+const syncComponentArtifacts = (handoff_1, ...args_1) => __awaiter(void 0, [handoff_1, ...args_1], void 0, function* (handoff, removedIds = []) {
+    var _a, _b;
     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 runtimeComponents = (_b = (_a = handoff.runtimeConfig) === null || _a === void 0 ? void 0 : _a.entities.components) !== null && _b !== void 0 ? _b : {};
     const runtimeIds = Object.keys(runtimeComponents);
     const entries = yield fs_extra_1.default.readdir(componentPath);
-    const discoveredArtifactIds = new Set(runtimeIds);
+    // `getArtifactComponentId` prunes a preview file only when it can name the owner. A deleted
+    // component is gone from the runtime config, and its `.json` is already removed, so nothing can
+    // match it. Naming it here restores the match without making its files valid. Every artifact it
+    // owns is then pruned, including the `__pattern_*` previews that the `.json` does not list.
+    const discoveredArtifactIds = new Set([...runtimeIds, ...removedIds]);
     for (const entry of entries) {
         const parsed = path_1.default.parse(entry);
         if (parsed.ext === '.json' || parsed.ext === '.js' || parsed.ext === '.css') {

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

@@ -71,9 +71,17 @@ var ComponentSegment;
     ComponentSegment["Previews"] = "previews";
     ComponentSegment["Validation"] = "validation";
 })(ComponentSegment || (exports.ComponentSegment = ComponentSegment = {}));
+/**
+ * A source format reads its previews out of the source file. A placeholder there is a preview
+ * nothing can render: the docs would offer a "Default" entry with no artifact. Only a renderer
+ * that renders whatever previews it is given needs the placeholder.
+ */
+const ownsItsPreviews = (data) => !!(data === null || data === void 0 ? void 0 : data.sourceFormat);
 const ensureDefaultPreview = (data) => {
     if (!data)
         return;
+    if (ownsItsPreviews(data))
+        return;
     if (!data.previews || Object.keys(data.previews).length === 0) {
         data.previews = {
             default: {
@@ -155,7 +163,7 @@ function processComponents(handoff, id, segmentToProcess, options) {
         const documentationObject = yield handoff.getDocumentationObject();
         const components = (_a = documentationObject === null || documentationObject === void 0 ? void 0 : documentationObject.components) !== null && _a !== void 0 ? _a : {};
         // Resolve the component set through the storage-agnostic store (v2). The filesystem store is a
-        // read view over `runtimeConfig.entries.components`, so these are the same records the build has
+        // read view over `runtimeConfig.entities.components`, so these are the same records the build has
         // always used — rebuilt into the id-keyed map the build logic below expects.
         const runtimeComponents = {};
         for (const component of yield handoff.store.components.list()) {
@@ -166,7 +174,7 @@ function processComponents(handoff, id, segmentToProcess, options) {
         if (id && !runtimeComponents[id]) {
             yield (0, artifacts_1.removeComponentApi)(handoff, id);
             yield (0, summary_1.removeComponentFromSummaryApi)(handoff, id);
-            yield (0, artifacts_1.syncComponentArtifacts)(handoff);
+            yield (0, artifacts_1.syncComponentArtifacts)(handoff, [id]);
             return [];
         }
         // Determine which components need building based on cache (when enabled)
@@ -268,7 +276,7 @@ function processComponents(handoff, id, segmentToProcess, options) {
             // If this is NOT a figma component, add the default generic preview.
             // We add it here (before merge) so that if the user explicitly provided previews in 'restMetadata',
             // those will override this default (standard "config overrides defaults" behavior).
-            if (!restMetadata.figmaComponentId) {
+            if (!restMetadata.figmaComponentId && !ownsItsPreviews(restMetadata)) {
                 componentDefaults.previews = {
                     default: {
                         title: 'Default',
@@ -296,12 +304,14 @@ function processComponents(handoff, id, segmentToProcess, options) {
                     data.css = existingData.css;
                     data.sass = existingData.sass;
                 }
-                // If we're not building previews, preserve pre-existing HTML, code snippet, usage, and previews.
+                // If we're not building previews, preserve pre-existing HTML, code snippet, usage, previews,
+                // and the code language they were rendered in.
                 if (!buildPlan.previews) {
                     data.html = existingData.html;
                     data.code = existingData.code;
                     data.usage = existingData.usage;
                     data.previews = existingData.previews;
+                    data.format = existingData.format;
                 }
                 /**
                  * Always keep validation results from the previous data,
@@ -396,19 +406,6 @@ function processComponents(handoff, id, segmentToProcess, options) {
  */
 const buildComponentSummary = (id, data) => {
     var _a;
-    return {
-        id,
-        title: data.title,
-        description: data.description,
-        type: data.type,
-        group: data.group,
-        image: data.image ? data.image : '',
-        figma: data.figma ? data.figma : '',
-        categories: data.categories ? data.categories : [],
-        tags: data.tags ? data.tags : [],
-        properties: data.properties,
-        previews: (0, previews_1.getDocumentedPreviews)(data.previews),
-        path: (0, url_1.buildComponentDetailUrl)(id, (_a = process.env.HANDOFF_APP_BASE_PATH) !== null && _a !== void 0 ? _a : ''),
-    };
+    return Object.assign(Object.assign({ id, title: data.title, description: data.description, type: data.type, group: data.group, image: data.image ? data.image : '', figma: data.figma ? data.figma : '', categories: data.categories ? data.categories : [], tags: data.tags ? data.tags : [], properties: data.properties, previews: (0, previews_1.getDocumentedPreviews)(data.previews), path: (0, url_1.buildComponentDetailUrl)(id, (_a = process.env.HANDOFF_APP_BASE_PATH) !== null && _a !== void 0 ? _a : '') }, (data.renderer ? { renderer: data.renderer } : {})), (data.sourceFormat ? { sourceFormat: data.sourceFormat } : {}));
 };
 exports.default = processComponents;

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

@@ -44,6 +44,8 @@ declare const buildComponentCss: (data: TransformComponentTokensResult, handoff:
         templates?: string;
     };
     renderer?: import("../../../index").RendererKind;
+    sourceFormat?: import("../../../index").SourceFormat;
+    componentExport?: string;
     options?: {
         preview?: {
             groupBy?: string;

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

@@ -16,7 +16,6 @@ exports.buildMainCss = exports.SHARED_COMPONENT_CSS_FILE = exports.MAIN_COMPONEN
 const fs_extra_1 = __importDefault(require("fs-extra"));
 const path_1 = __importDefault(require("path"));
 const vite_1 = require("vite");
-const config_1 = require("../../../config");
 const duration_1 = require("../../../utils/duration");
 const logger_1 = require("../../../utils/logger");
 const vite_config_1 = __importDefault(require("../../vite-config"));
@@ -163,14 +162,14 @@ const buildComponentCss = (data, handoff) => __awaiter(void 0, void 0, void 0, f
  * Build the main CSS file using Vite
  */
 const buildMainCss = (handoff) => __awaiter(void 0, void 0, void 0, function* () {
-    var _a, _b, _c;
+    var _a, _b;
     const outputPath = (0, component_1.getComponentOutputPath)(handoff);
     const mainCssPath = path_1.default.resolve(outputPath, exports.MAIN_COMPONENT_CSS_FILE);
-    const runtimeConfig = (0, config_1.initRuntimeConfig)(handoff)[0];
-    if (((_a = runtimeConfig === null || runtimeConfig === void 0 ? void 0 : runtimeConfig.entries) === null || _a === void 0 ? void 0 : _a.scss) && fs_extra_1.default.existsSync(runtimeConfig.entries.scss)) {
-        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)) {
+    const scssEntry = (_b = (_a = handoff.runtimeConfig) === null || _a === void 0 ? void 0 : _a.entries) === null || _b === void 0 ? void 0 : _b.scss;
+    if (scssEntry && fs_extra_1.default.existsSync(scssEntry)) {
+        const stat = yield fs_extra_1.default.stat(scssEntry);
+        const entryPath = stat.isDirectory() ? path_1.default.resolve(scssEntry, 'main.scss') : scssEntry;
+        if (entryPath === scssEntry || fs_extra_1.default.existsSync(entryPath)) {
             logger_1.Logger.info(`Building styles for global entry (${exports.MAIN_COMPONENT_CSS_FILE})…`);
             const startedAt = Date.now();
             // Drop the previous artifact so a failed/empty rebuild cannot preserve stale global CSS that
@@ -178,13 +177,11 @@ const buildMainCss = (handoff) => __awaiter(void 0, void 0, void 0, function* ()
             yield fs_extra_1.default.remove(mainCssPath);
             try {
                 const loadPaths = [
+                    path_1.default.dirname(scssEntry),
                     path_1.default.resolve(handoff.workingPath),
                     path_1.default.resolve(handoff.workingPath, handoff.exportsDirectory, handoff.getProjectId()),
                     path_1.default.resolve(handoff.workingPath, 'node_modules'),
                 ];
-                if ((_c = (_b = handoff.runtimeConfig) === null || _b === void 0 ? void 0 : _b.entries) === null || _c === void 0 ? void 0 : _c.scss) {
-                    loadPaths.unshift(path_1.default.dirname(handoff.runtimeConfig.entries.scss));
-                }
                 yield buildCssBundle({
                     entry: entryPath,
                     outputPath,
@@ -194,7 +191,7 @@ const buildMainCss = (handoff) => __awaiter(void 0, void 0, void 0, function* ()
                 });
                 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) {
+            catch (_c) {
                 // buildCssBundle already logs failure for the entry path; ensure no stale artifact remains.
                 yield fs_extra_1.default.remove(mainCssPath);
             }

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

@@ -19,15 +19,17 @@ const logger_1 = require("../../../utils/logger");
 const plugins_1 = require("../../plugins");
 const vite_config_1 = __importDefault(require("../../vite-config"));
 const component_1 = require("../component");
-const resolveRenderer = (data) => {
-    var _a, _b, _c;
-    const templatePath = ((_a = data.entries) === null || _a === void 0 ? void 0 : _a.template) || '';
-    return (data.renderer ||
-        (((_b = data.entries) === null || _b === void 0 ? void 0 : _b.story) || templatePath.match(/\.stories\.(jsx|tsx|js|ts)$/) ? 'csf' : undefined) ||
-        (((_c = data.entries) === null || _c === void 0 ? void 0 : _c.component) || (templatePath.includes('.tsx') && !templatePath.match(/\.stories\.(jsx|tsx|js|ts)$/))
-            ? 'react'
-            : undefined) ||
-        (templatePath.includes('.hbs') ? 'handlebars' : undefined));
+/**
+ * Exactly one entry builds an item. A source format claims it before its renderer, because a CSF
+ * item is also a React item and both plugins would write their own previews. The maps are
+ * exhaustive, so a new renderer fails to compile until its previews are built.
+ */
+const FORMAT_PLUGINS = {
+    csf: (data, components, handoff) => [(0, plugins_1.csfRenderPlugin)(data, components, handoff)],
+};
+const RENDERER_PLUGINS = {
+    handlebars: (data, components, handoff) => [(0, plugins_1.handlebarsPreviewsPlugin)(data, components, handoff)],
+    react: (data, components, handoff) => [(0, plugin_react_1.default)(), (0, plugins_1.ssrRenderPlugin)(data, components, handoff)],
 };
 /**
  * Builds previews for components using Vite and Handlebars.
@@ -47,13 +49,13 @@ const buildPreviews = (data, handoff, components) => __awaiter(void 0, void 0, v
     var _a, _b, _c;
     if (!((_a = data.entries) === null || _a === void 0 ? void 0 : _a.template))
         return data;
-    const resolvedRenderer = resolveRenderer(data);
-    const plugins = [
-        ...(vite_config_1.default.plugins || []),
-        ...(resolvedRenderer === 'handlebars' ? [(0, plugins_1.handlebarsPreviewsPlugin)(data, components, handoff)] : []),
-        ...(resolvedRenderer === 'csf' ? [(0, plugins_1.csfRenderPlugin)(data, components, handoff)] : []),
-        ...(resolvedRenderer === 'react' ? [(0, plugin_react_1.default)(), (0, plugins_1.ssrRenderPlugin)(data, components, handoff)] : []),
-    ];
+    const { renderer, sourceFormat } = data;
+    const previewPlugins = sourceFormat ? FORMAT_PLUGINS[sourceFormat] : RENDERER_PLUGINS[renderer];
+    if (!previewPlugins) {
+        logger_1.Logger.error(`No preview support for renderer "${renderer}"${sourceFormat ? ` and source format "${sourceFormat}"` : ''}: ${data.entries.template}`);
+        return data;
+    }
+    const plugins = [...(vite_config_1.default.plugins || []), ...previewPlugins(data, components, handoff)];
     // Store the current NODE_ENV value before vite build
     // This is necessary because viteBuild forcibly sets NODE_ENV to 'production'
     // which can cause issues with subsequent Next.js operations that rely on

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

@@ -16,7 +16,6 @@ exports.buildMainJS = exports.buildComponentJs = exports.MAIN_COMPONENT_JS_FILE
 const fs_extra_1 = __importDefault(require("fs-extra"));
 const path_1 = __importDefault(require("path"));
 const vite_1 = require("vite");
-const config_1 = require("../../../config");
 const duration_1 = require("../../../utils/duration");
 const logger_1 = require("../../../utils/logger");
 const vite_config_1 = __importDefault(require("../../vite-config"));
@@ -135,11 +134,10 @@ exports.buildComponentJs = buildComponentJs;
  * @returns A Promise that resolves when the build process is complete
  */
 const buildMainJS = (handoff) => __awaiter(void 0, void 0, void 0, function* () {
-    var _a;
+    var _a, _b;
     const outputPath = (0, component_1.getComponentOutputPath)(handoff);
     const mainJsPath = path_1.default.resolve(outputPath, exports.MAIN_COMPONENT_JS_FILE);
-    const runtimeConfig = (0, config_1.initRuntimeConfig)(handoff)[0];
-    const entry = (_a = runtimeConfig === null || runtimeConfig === void 0 ? void 0 : runtimeConfig.entries) === null || _a === void 0 ? void 0 : _a.js;
+    const entry = (_b = (_a = handoff.runtimeConfig) === null || _a === void 0 ? void 0 : _a.entries) === null || _b === void 0 ? void 0 : _b.js;
     // No usable global JS entry: drop any stale artifact and emit nothing to reference.
     if (!entry || !fs_extra_1.default.existsSync(path_1.default.resolve(entry))) {
         if (entry) {

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

@@ -25,54 +25,70 @@ const html_1 = require("./html");
  * Returns pattern ids whose declarations reference any of the given component ids.
  */
 const getPatternIdsReferencingComponents = (handoff, componentIds) => {
-    var _a, _b, _c, _d;
+    var _a, _b, _c;
     if (componentIds.length === 0) {
         return [];
     }
     const idSet = new Set(componentIds);
-    const runtimePatterns = (_c = (_b = (_a = handoff.runtimeConfig) === null || _a === void 0 ? void 0 : _a.entries) === null || _b === void 0 ? void 0 : _b.patterns) !== null && _c !== void 0 ? _c : {};
+    const runtimePatterns = (_b = (_a = handoff.runtimeConfig) === null || _a === void 0 ? void 0 : _a.entities.patterns) !== null && _b !== void 0 ? _b : {};
     const result = [];
     for (const patternId of Object.keys(runtimePatterns)) {
         const pattern = runtimePatterns[patternId];
-        if ((_d = pattern.components) === null || _d === void 0 ? void 0 : _d.some((ref) => idSet.has(ref.id))) {
+        if ((_c = pattern.components) === null || _c === void 0 ? void 0 : _c.some((ref) => idSet.has(ref.id))) {
             result.push(patternId);
         }
     }
     return result;
 };
 exports.getPatternIdsReferencingComponents = getPatternIdsReferencingComponents;
+/** Collapses repeats into one item with a count, so one cause reads as one problem. */
+const summarizeReasons = (reasons) => {
+    var _a;
+    const counts = new Map();
+    for (const reason of reasons) {
+        counts.set(reason, ((_a = counts.get(reason)) !== null && _a !== void 0 ? _a : 0) + 1);
+    }
+    return Array.from(counts, ([reason, count]) => (count > 1 ? `${reason} (x${count})` : reason)).join('; ');
+};
 function buildPattern(handoff, patternId, pattern, componentOutputDir, basePath, sharedArtifacts) {
     return __awaiter(this, void 0, void 0, function* () {
+        var _a, _b, _c;
         const fragments = [];
-        let hasErrors = false;
-        for (let i = 0; i < pattern.components.length; i++) {
-            const ref = pattern.components[i];
+        // Composition is what drops a ref, so it is also what reports why. Discovery recorded its reason
+        // without logging it, and that reason is more precise than the one this loop can build.
+        const skipped = [];
+        const composedWithFallback = [];
+        for (const ref of pattern.components) {
             if (ref.resolved === false && !ref.resolvedPreview) {
-                hasErrors = true;
+                skipped.push((_a = ref.unresolvedReason) !== null && _a !== void 0 ? _a : `component "${ref.id}" did not resolve`);
                 continue;
             }
             const previewKey = ref.resolvedPreview || ref.preview;
             if (!previewKey) {
-                const error = `Pattern "${patternId}" component[${i}] ("${ref.id}") has no resolved preview key. Skipping.`;
-                logger_1.Logger.warn(error);
+                skipped.push((_b = ref.unresolvedReason) !== null && _b !== void 0 ? _b : `component "${ref.id}" has no preview to render`);
                 ref.resolved = false;
-                hasErrors = true;
                 continue;
             }
             const htmlFileName = `${ref.id}-${previewKey}.html`;
             const htmlFilePath = path_1.default.resolve(componentOutputDir, htmlFileName);
             if (!fs_extra_1.default.existsSync(htmlFilePath)) {
-                const error = `Pattern "${patternId}" component[${i}] ("${ref.id}") preview file not found: ${htmlFileName}. ` +
-                    `Ensure the component has a preview named "${previewKey}".`;
-                logger_1.Logger.warn(error);
+                skipped.push((_c = ref.unresolvedReason) !== null && _c !== void 0 ? _c : `preview "${previewKey}" of component "${ref.id}" was not built (${htmlFileName})`);
                 ref.resolved = false;
-                hasErrors = true;
                 continue;
             }
             ref.resolved = true;
+            if (ref.unresolvedReason) {
+                composedWithFallback.push(ref.unresolvedReason);
+            }
             const html = yield fs_extra_1.default.readFile(htmlFilePath, 'utf8');
             fragments.push({ componentId: ref.id, html });
         }
+        if (skipped.length > 0) {
+            logger_1.Logger.warn(`Pattern "${patternId}" skipped ${skipped.length} of ${pattern.components.length} fragment(s): ${summarizeReasons(skipped)}.`);
+        }
+        if (composedWithFallback.length > 0) {
+            logger_1.Logger.warn(`Pattern "${patternId}" composed ${composedWithFallback.length} fragment(s) from a fallback: ${summarizeReasons(composedWithFallback)}.`);
+        }
         // Resolve component-owned artifact presence for each composed component so the pattern references
         // only the stylesheets that actually exist (no dangling references for style-less components).
         const componentArtifacts = new Map();
@@ -85,9 +101,6 @@ function buildPattern(handoff, patternId, pattern, componentOutputDir, basePath,
             logger_1.Logger.warn(`Pattern "${patternId}" produced no fragments. Skipping.`);
             return null;
         }
-        if (hasErrors) {
-            logger_1.Logger.warn(`Pattern "${patternId}" has missing components but will be composed from available fragments.`);
-        }
         const composedHtml = (0, html_1.composePatternHtml)(patternId, pattern.title, fragments, basePath, sharedArtifacts, componentArtifacts);
         const patternUrl = `${patternId}.html`;
         const patternData = Object.assign(Object.assign({}, pattern), { id: patternId, url: patternUrl, path: (0, url_1.buildPatternDetailUrl)(patternId, basePath) });
@@ -106,7 +119,7 @@ function processPatterns(handoff, options) {
     return __awaiter(this, void 0, void 0, function* () {
         var _a;
         // Resolve the pattern set through the storage-agnostic store (v2). The filesystem store is a read
-        // view over `runtimeConfig.entries.patterns`, so these are the same records the build has always
+        // view over `runtimeConfig.entities.patterns`, so these are the same records the build has always
         // used — rebuilt into the id-keyed map the build logic below expects.
         const runtimePatterns = {};
         for (const pattern of yield handoff.store.patterns.list()) {

package/dist/transformers/preview/types.d.ts

@@ -1,6 +1,6 @@
 import type { GeneratedDocs } from 'handoff-docgen';
 import { Card } from '../../app/components/Component/Cards';
-import type { RendererKind } from '../../declarations/types';
+import type { RendererKind, SourceFormat } from '../../catalog/renderers';
 import { ValidationResult } from '../../types/preview';
 import { Filter } from '../../utils/filter';
 import { SlotMetadata } from './component';
@@ -105,6 +105,13 @@ export type ComponentObject = {
     };
     /** Optional explicit renderer id */
     renderer?: RendererKind;
+    /**
+     * Implementation source format, such as CSF. The separate `format` field describes the preview code language.
+     * These names must differ because the build spreads this record over the preview.
+     */
+    sourceFormat?: SourceFormat;
+    /** Export of `entries.component` that holds the implementation. Defaults to the default export. */
+    componentExport?: string;
     /** Schema describing the expected properties (props/slots) for the component */
     properties: {
         [key: string]: SlotMetadata;
@@ -113,6 +120,8 @@ export type ComponentObject = {
     previews: {
         [key: string]: OptionalPreviewRender;
     };
+    /** Source export order retained when publishing previews through jsonb storage. */
+    previewOrder?: string[];
     /** Internal previews generated only for pattern composition, not public docs */
     internalPatternPreviews?: {
         [key: string]: OptionalPreviewRender;
@@ -180,6 +189,9 @@ export type TransformComponentTokensResult = {
         templates?: string;
     };
     renderer?: RendererKind;
+    /** See `ComponentObject.sourceFormat`. Distinct from `format`, the preview's code language. */
+    sourceFormat?: SourceFormat;
+    componentExport?: string;
     options?: {
         preview?: {
             groupBy?: string;
@@ -213,6 +225,8 @@ export type PatternComponentEntry = {
     resolvedPreview?: string;
     /** Whether the pattern entry resolved to a usable component preview */
     resolved?: boolean;
+    /** Why discovery could not resolve this entry as authored. The pattern build reports it. */
+    unresolvedReason?: string;
 };
 export type PatternObject = {
     title: string;

package/dist/types/config.d.ts

@@ -98,22 +98,20 @@ export interface ConfigEntries {
      * @example "scripts/main.js"
      */
     js?: string;
+}
+/** Catalog item registration. */
+export interface ConfigCatalog {
     /**
-     * Array of component paths to be included in the build
-     * @example ["components/button", "components/input"]
-     */
-    components?: string[];
-    /**
-     * Array of pattern paths to be included in the build.
-     * Patterns compose multiple component previews into single-page views.
-     * @example ["patterns/hero-section", "patterns"]
+     * Directories to search for catalog items. A path is either an item directory or a collection
+     * directory whose subdirectories are each treated as an item.
+     * @example ["components", "patterns"]
      */
-    patterns?: string[];
+    include?: string[];
 }
 /** Runtime mode. Resolved solely from `runtime.mode`; never inferred from env vars or connection settings. */
 export type RuntimeMode = 'workspace' | 'registry';
 /** Format used when synthesizing local workspace declarations. */
-export type DeclarationFormat = 'ts' | 'js' | 'cjs' | 'json';
+export type DeclarationFormat = 'ts' | 'js' | 'cjs';
 /**
  * User-facing `runtime` configuration block. A single optional block that selects the runtime
  * mode and carries mode-specific host/connection settings.
@@ -127,6 +125,13 @@ export interface HandoffRuntimeConfig {
      * Mode is never inferred from environment variables, database settings, or token presence.
      */
     mode?: RuntimeMode;
+    /**
+     * Whether the app serves the `/api/mcp/` Model Context Protocol endpoint. Set to `false` to leave
+     * the endpoint and the header affordance out of the build; the route then answers 404. Like
+     * `mode`, this is config-only and baked at build time, so changing it needs a rebuild.
+     * @default true
+     */
+    mcp?: boolean;
     /** Workspace-mode settings. */
     workspace?: {
         entries?: ConfigEntries;
@@ -220,6 +225,10 @@ export interface Config {
      * Configuration for entry points to assets and components that will be built
      */
     entries?: ConfigEntries;
+    /**
+     * Where catalog items are registered.
+     */
+    catalog?: ConfigCatalog;
     /**
      * Override URLs for the asset zip download links. When unset, each link defaults to the
      * basePath-aware asset route `{basePath}/api/docs/assets/{collection}/{collection}.zip`, served by
@@ -397,11 +406,22 @@ export interface ConfigFileEntry {
     kind: string;
     entityId: string;
 }
+/** A catalog declaration skipped because another declaration already took its id. */
+export interface DuplicateCatalogId {
+    id: string;
+    /** Absolute path of the declaration that owns the id. */
+    kept: string;
+    /** Absolute path of the declaration that was skipped. */
+    skipped: string;
+}
 export interface RuntimeConfig {
+    /** Resolved absolute paths of the project-wide bundle entry points, from `config.entries`. */
     entries?: {
         scss?: string;
         js?: string;
-        templates?: string;
+    };
+    /** Entities discovered from the workspace, keyed by id. Always present, possibly empty. */
+    entities: {
         components: {
             [id: string]: ComponentListObject;
         };
@@ -412,6 +432,11 @@ export interface RuntimeConfig {
             [id: string]: PageListObject;
         };
     };
+    /**
+     * Catalog declarations skipped because their id was already taken. Always present, possibly empty.
+     * Discovery is the only pass that sees both declarations, so publish reads the duplicates from here.
+     */
+    duplicateCatalogIds: DuplicateCatalogId[];
     options: {
         [key: string]: RuntimeConfigComponentOptions;
     };

package/docs/api.md

@@ -1,5 +1,8 @@
 # Handoff API
 
+Register implementations and compositions with `defineCatalogItem`. See the
+[catalog examples](../README.md#catalog-items) and [version 1.x.x to version 2.x.x migration guide](../UPGRADE.md#version-1xx-to-version-2xx).
+
 Handoff exposes two APIs - A Javascript API for interacting with the pipeline
 Handoff exposes a Javascript API allowing you to easily integrate Handoff into
 existing Node based applications, CI/CD, and command line tools. This API also

package/docs/cli.md

@@ -63,7 +63,7 @@ Commands:
   logout [--url <registry-url>] - Revokes the saved token when possible, then removes the local credential.
 
   make
-    make:template <component> <state> [opts] - Creates a new template
+    make:component <name> [opts] - Creates a new catalog item with a declaration
     make:page <component> <state> [opts] - Creates a new page
 
   eject - Ejects the default entire configuration to the current directory

package/drizzle/0006_add_component_source_format.sql

@@ -0,0 +1,3 @@
+ALTER TABLE "components" ADD COLUMN "source_format" text;--> statement-breakpoint
+-- Backfill from the authoritative record so components published before this migration get a value too.
+UPDATE "components" SET "source_format" = "record"->>'sourceFormat' WHERE "record"->>'sourceFormat' IS NOT NULL;