handoff-app 2.0.0-5 → 2.0.0-7

package/dist/config/defaults.js

@@ -1,7 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getClientConfig = exports.defaultConfig = void 0;
+exports.getClientConfig = exports.defaultConfig = exports.isMcpEnabled = void 0;
 const connection_1 = require("../registry/connection");
+/** Whether the MCP endpoint is served. On unless `runtime.mcp` is explicitly `false`. */
+const isMcpEnabled = (config) => { var _a; return ((_a = config === null || config === void 0 ? void 0 : config.runtime) === null || _a === void 0 ? void 0 : _a.mcp) !== false; };
+exports.isMcpEnabled = isMcpEnabled;
 const defaultConfig = () => {
     var _a, _b, _c, _d;
     return ({

package/dist/config/index.d.ts

@@ -1,9 +1,9 @@
-export { defaultConfig, getClientConfig } from './defaults';
+export { defaultConfig, getClientConfig, isMcpEnabled } from './defaults';
 export type { ImageStyle } from './defaults';
 export { HandoffConfigError, initConfig, initConfigWithMetadata } from './loader';
 export type { ConfigLoadContext } from './loader';
 export { defineConfig } from './helpers';
 export { initRuntimeConfig } from './runtime';
 export { validateConfig } from './validator';
-export { isEntryCovered, writeEntries } from './entries';
-export type { EntryKind, WriteEntriesResult } from './entries';
+export { addToCatalog, isIncluded } from './catalog-include';
+export type { AddToCatalogResult } from './catalog-include';

package/dist/config/index.js

@@ -1,10 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.writeEntries = exports.isEntryCovered = exports.validateConfig = exports.initRuntimeConfig = exports.defineConfig = exports.initConfigWithMetadata = exports.initConfig = exports.HandoffConfigError = exports.getClientConfig = exports.defaultConfig = void 0;
+exports.isIncluded = exports.addToCatalog = exports.validateConfig = exports.initRuntimeConfig = exports.defineConfig = exports.initConfigWithMetadata = exports.initConfig = exports.HandoffConfigError = exports.isMcpEnabled = exports.getClientConfig = exports.defaultConfig = void 0;
 // Config defaults and client config
 var defaults_1 = require("./defaults");
 Object.defineProperty(exports, "defaultConfig", { enumerable: true, get: function () { return defaults_1.defaultConfig; } });
 Object.defineProperty(exports, "getClientConfig", { enumerable: true, get: function () { return defaults_1.getClientConfig; } });
+Object.defineProperty(exports, "isMcpEnabled", { enumerable: true, get: function () { return defaults_1.isMcpEnabled; } });
 // Config file loading
 var loader_1 = require("./loader");
 Object.defineProperty(exports, "HandoffConfigError", { enumerable: true, get: function () { return loader_1.HandoffConfigError; } });
@@ -19,7 +20,7 @@ Object.defineProperty(exports, "initRuntimeConfig", { enumerable: true, get: fun
 // Config validation
 var validator_1 = require("./validator");
 Object.defineProperty(exports, "validateConfig", { enumerable: true, get: function () { return validator_1.validateConfig; } });
-// Registering directory-list entries (components/patterns)
-var entries_1 = require("./entries");
-Object.defineProperty(exports, "isEntryCovered", { enumerable: true, get: function () { return entries_1.isEntryCovered; } });
-Object.defineProperty(exports, "writeEntries", { enumerable: true, get: function () { return entries_1.writeEntries; } });
+// Registering catalog item directories under `catalog.include`
+var catalog_include_1 = require("./catalog-include");
+Object.defineProperty(exports, "addToCatalog", { enumerable: true, get: function () { return catalog_include_1.addToCatalog; } });
+Object.defineProperty(exports, "isIncluded", { enumerable: true, get: function () { return catalog_include_1.isIncluded; } });

package/dist/config/loader.js

@@ -104,7 +104,7 @@ const resolveConfigFilePath = (workingPath, requestedPath) => {
  * Loads the handoff configuration for the given working directory and returns metadata.
  */
 const initConfigWithMetadata = (configOverride, context) => {
-    var _a;
+    var _a, _b, _c;
     let config = {};
     const { selected: configPath, ignored } = resolveConfigFilePath((_a = context === null || context === void 0 ? void 0 : context.workingPath) !== null && _a !== void 0 ? _a : (0, path_2.resolveWorkingPath)(), context === null || context === void 0 ? void 0 : context.configPath);
     if (ignored.length > 0 && configPath) {
@@ -123,6 +123,14 @@ const initConfigWithMetadata = (configOverride, context) => {
             }
         });
     }
+    const entries = config.entries;
+    if (entries && ('components' in entries || 'patterns' in entries)) {
+        throw new HandoffConfigError('entries.components and entries.patterns were removed. Use catalog.include. See UPGRADE.md#catalog-items.');
+    }
+    const format = (_c = (_b = config.runtime) === null || _b === void 0 ? void 0 : _b.workspace) === null || _c === void 0 ? void 0 : _c.declarationFormat;
+    if (format !== undefined && !['ts', 'js', 'cjs'].includes(format)) {
+        throw new HandoffConfigError('Item declarations support ts, js, and cjs. Convert JSON declarations to defineCatalogItem. See UPGRADE.md#catalog-items.');
+    }
     const defaults = (0, defaults_1.defaultConfig)();
     // Top-level merge stays shallow to preserve 1.x semantics, except for the `runtime`
     // block which is deep-merged so a partial user `runtime` (e.g. only `mode`) does not

package/dist/config/runtime.d.ts

@@ -12,6 +12,10 @@ type DeclarationResolution = {
     fileName: string;
 };
 export declare const resolveComponentDeclaration: (componentDir: string, componentBaseName: string) => DeclarationResolution | null;
+/**
+ * Expands catalog.include into item directories and removes duplicate paths.
+ */
+export declare const getCatalogItemDirectories: (config: Config, workingPath: string) => string[];
 /**
  * Initializes the runtime configuration by resolving component entries,
  * SCSS/JS paths, and transformer options from the handoff config.
@@ -22,7 +26,7 @@ export declare const resolveComponentDeclaration: (componentDir: string, compone
 export declare const initRuntimeConfig: (handoff: HandoffContext) => [runtimeConfig: RuntimeConfig, configs: string[], configFileIndex: Map<string, ConfigFileEntry>];
 /**
  * True when `searchPath` is itself a single component directory: it holds a declaration file named
- * after the directory (`{dirname}.handoff.*`, or a legacy `{dirname}.{json,js,cjs}`). This is what
+ * with a .handoff.ts, .handoff.js, or .handoff.cjs suffix. This is what
  * separates a declared component from a collection directory.
  */
 export declare const isComponentDirectory: (searchPath: string) => boolean;
@@ -34,11 +38,6 @@ export declare const isComponentDirectory: (searchPath: string) => boolean;
  * @returns Paths to the component directories.
  */
 export declare const getComponentsForPath: (searchPath: string) => string[];
-/**
- * Generic directory discovery for both components and patterns.
- * Reuses the same logic as getComponentsForPath.
- */
-export declare const getItemsForPath: (searchPath: string) => string[];
 /**
  * Recursively converts all keys and string values in an object to lowercase.
  */

package/dist/config/runtime.js

@@ -3,11 +3,12 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.toLowerCaseKeysAndValues = exports.getItemsForPath = exports.getComponentsForPath = exports.isComponentDirectory = exports.initRuntimeConfig = exports.resolveComponentDeclaration = void 0;
+exports.toLowerCaseKeysAndValues = exports.getComponentsForPath = exports.isComponentDirectory = exports.initRuntimeConfig = exports.getCatalogItemDirectories = exports.resolveComponentDeclaration = void 0;
 const esbuild_1 = __importDefault(require("esbuild"));
 const fs_extra_1 = __importDefault(require("fs-extra"));
 const module_1 = require("module");
 const path_1 = __importDefault(require("path"));
+const catalog_1 = require("../catalog");
 const content_kinds_1 = require("../registry/content-kinds");
 const csf_1 = require("../transformers/utils/csf");
 const module_2 = require("../transformers/utils/module");
@@ -15,51 +16,31 @@ const logger_1 = require("../utils/logger");
 const markdown_1 = require("../utils/markdown");
 const pages_1 = require("../utils/pages");
 const path_2 = require("../utils/path");
-const declaration_1 = require("./normalizers/declaration");
 const page_1 = require("./normalizers/page");
-const pattern_1 = require("./normalizers/pattern");
-const MODERN_EXTENSIONS = ['ts', 'js', 'cjs', 'json'];
-const getLegacyDeclarationFiles = (componentBaseName) => [
-    `${componentBaseName}.json`,
-    `${componentBaseName}.js`,
-    `${componentBaseName}.cjs`,
-];
-const getModernDeclarationFiles = (componentBaseName) => MODERN_EXTENSIONS.map((ext) => `${componentBaseName}.handoff.${ext}`);
-const findPreferredModernDeclaration = (componentDir, componentBaseName) => {
-    const exactCandidates = getModernDeclarationFiles(componentBaseName);
+const DECLARATION_EXTENSIONS = ['ts', 'js', 'cjs'];
+const getDeclarationFiles = (componentBaseName) => DECLARATION_EXTENSIONS.map((ext) => `${componentBaseName}.handoff.${ext}`);
+const findPreferredDeclaration = (componentDir, componentBaseName) => {
+    const exactCandidates = getDeclarationFiles(componentBaseName);
     const exactMatch = exactCandidates.find((candidate) => fs_extra_1.default.existsSync(path_1.default.resolve(componentDir, candidate)));
     if (exactMatch)
         return exactMatch;
     const allFiles = fs_extra_1.default.existsSync(componentDir) ? fs_extra_1.default.readdirSync(componentDir) : [];
-    const modernFiles = allFiles
-        .filter((file) => /\.handoff\.(ts|js|cjs|json)$/.test(file))
-        .sort((a, b) => a.localeCompare(b));
-    if (!modernFiles.length)
+    const declarationFiles = allFiles.filter((file) => /\.handoff\.(ts|js|cjs)$/.test(file)).sort((a, b) => a.localeCompare(b));
+    if (!declarationFiles.length)
         return undefined;
-    for (const ext of MODERN_EXTENSIONS) {
-        const extMatch = modernFiles.find((file) => file.endsWith(`.handoff.${ext}`));
+    for (const ext of DECLARATION_EXTENSIONS) {
+        const extMatch = declarationFiles.find((file) => file.endsWith(`.handoff.${ext}`));
         if (extMatch)
             return extMatch;
     }
-    return modernFiles[0];
+    return declarationFiles[0];
 };
 const resolveComponentDeclaration = (componentDir, componentBaseName) => {
-    const modernMatch = findPreferredModernDeclaration(componentDir, componentBaseName);
-    const legacyFiles = getLegacyDeclarationFiles(componentBaseName);
-    const legacyMatch = legacyFiles.find((candidate) => fs_extra_1.default.existsSync(path_1.default.resolve(componentDir, candidate)));
-    if (modernMatch) {
-        if (legacyMatch) {
-            logger_1.Logger.warn(`Both modern and legacy declarations found in "${componentDir}". Using "${modernMatch}" and ignoring "${legacyMatch}".`);
-        }
-        return { fileName: modernMatch };
-    }
-    if (legacyMatch) {
-        return { fileName: legacyMatch };
-    }
-    return null;
+    const declarationMatch = findPreferredDeclaration(componentDir, componentBaseName);
+    return declarationMatch ? { fileName: declarationMatch } : null;
 };
 exports.resolveComponentDeclaration = resolveComponentDeclaration;
-const evaluateTypeScriptDeclaration = (filePath, handoffModulePath) => {
+const evaluateDeclaration = (filePath, handoffModulePath) => {
     var _a, _b;
     const buildResult = esbuild_1.default.buildSync({
         entryPoints: [filePath],
@@ -91,26 +72,16 @@ const evaluateTypeScriptDeclaration = (filePath, handoffModulePath) => {
     evaluator(runtimeRequire, mod, mod.exports, filePath, path_1.default.dirname(filePath));
     return mod.exports;
 };
-const loadDeclarationFile = (filePath, handoffModulePath) => {
-    if (filePath.endsWith('.json')) {
-        const componentJson = fs_extra_1.default.readFileSync(filePath, 'utf8');
-        return JSON.parse(componentJson);
-    }
-    if (filePath.endsWith('.ts')) {
-        return evaluateTypeScriptDeclaration(filePath, handoffModulePath);
-    }
-    // Invalidate require cache to ensure fresh read
-    delete require.cache[require.resolve(filePath)];
-    return require(filePath);
-};
+const loadDeclarationFile = evaluateDeclaration;
 const discoverCsfPreviews = (component, handoff) => {
     var _a;
-    if (component.renderer !== 'csf' || !((_a = component.entries) === null || _a === void 0 ? void 0 : _a.template)) {
+    if (component.sourceFormat !== 'csf' || !((_a = component.entries) === null || _a === void 0 ? void 0 : _a.template)) {
         return component.previews;
     }
     try {
         const loaded = (0, module_2.buildAndEvaluateModuleSync)(component.entries.template, handoff);
-        const discoveredPreviews = (0, csf_1.createCsfStoryPreviews)(loaded.exports);
+        // esbuild emits its export map alphabetically, so story order comes from the source text.
+        const discoveredPreviews = (0, catalog_1.orderPreviews)((0, csf_1.createCsfStoryPreviews)(loaded.exports), (0, catalog_1.readExportOrder)(component.entries.template));
         if (Object.keys(discoveredPreviews).length === 0) {
             logger_1.Logger.warn(`No named stories found in CSF file for "${component.id}": ${component.entries.template}`);
             return component.previews;
@@ -123,6 +94,49 @@ const discoverCsfPreviews = (component, handoff) => {
         return component.previews;
     }
 };
+/**
+ * Expands catalog.include into item directories and removes duplicate paths.
+ */
+const getCatalogItemDirectories = (config, workingPath) => {
+    var _a, _b;
+    const registered = [...((_b = (_a = config.catalog) === null || _a === void 0 ? void 0 : _a.include) !== null && _b !== void 0 ? _b : [])];
+    const seen = new Set();
+    const directories = [];
+    for (const included of registered) {
+        for (const directory of (0, exports.getComponentsForPath)(path_1.default.resolve(workingPath, included))) {
+            const key = (0, path_2.normalizePathForCompare)(directory);
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            directories.push(directory);
+        }
+    }
+    return directories;
+};
+exports.getCatalogItemDirectories = getCatalogItemDirectories;
+/**
+ * Records the React component a CSF file documents, so it is watched, documented, and published.
+ * `csf-render` reads `meta.component` as a value; only the source text says which file it came
+ * from. A component outside the item directory is left unrecorded, because publish rejects a
+ * source path that escapes the entity directory.
+ */
+const resolveCsfComponentSource = (component) => {
+    var _a, _b;
+    if (component.sourceFormat !== 'csf')
+        return;
+    const storyPath = (_a = component.entries) === null || _a === void 0 ? void 0 : _a.story;
+    if (!storyPath || ((_b = component.entries) === null || _b === void 0 ? void 0 : _b.component))
+        return;
+    const resolved = (0, catalog_1.resolvePropertySource)(storyPath, 'component');
+    if (!resolved)
+        return;
+    if (!(0, catalog_1.isInsideDirectory)(resolved.file, component.path)) {
+        logger_1.Logger.warn(`Catalog item "${component.id}" documents a component at "${resolved.file}", outside "${component.path}". ` +
+            `Previews still build, but that file is not published. Move it into the item directory to publish it.`);
+        return;
+    }
+    component.entries.component = resolved.file;
+};
 /**
  * Initializes the runtime configuration by resolving component entries,
  * SCSS/JS paths, and transformer options from the handoff config.
@@ -131,8 +145,8 @@ const discoverCsfPreviews = (component, handoff) => {
  * @returns A tuple of [RuntimeConfig, configFilePaths, configFileIndex].
  */
 const initRuntimeConfig = (handoff) => {
-    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k;
-    var _l;
+    var _a, _b, _c, _d, _e, _f;
+    var _g;
     const configFiles = [];
     const configFileIndex = new Map();
     const result = {
@@ -140,103 +154,96 @@ const initRuntimeConfig = (handoff) => {
         entries: {
             scss: undefined,
             js: undefined,
+        },
+        entities: {
             components: {},
             patterns: {},
             pages: {},
         },
+        duplicateCatalogIds: [],
     };
+    // The id addresses artifacts, transfer routes and docs URLs, so it has to resolve to one item.
+    // Components and patterns share one namespace, so one map covers both lanes.
+    const declaredIds = new Map();
     if (!!((_a = handoff.config.entries) === null || _a === void 0 ? void 0 : _a.scss)) {
         result.entries.scss = path_1.default.resolve(handoff.workingPath, (_b = handoff.config.entries) === null || _b === void 0 ? void 0 : _b.scss);
     }
     if (!!((_c = handoff.config.entries) === null || _c === void 0 ? void 0 : _c.js)) {
         result.entries.js = path_1.default.resolve(handoff.workingPath, (_d = handoff.config.entries) === null || _d === void 0 ? void 0 : _d.js);
     }
-    if ((_f = (_e = handoff.config.entries) === null || _e === void 0 ? void 0 : _e.components) === null || _f === void 0 ? void 0 : _f.length) {
-        const componentPaths = handoff.config.entries.components.flatMap(exports.getComponentsForPath);
-        for (const componentPath of componentPaths) {
-            const resolvedComponentPath = path_1.default.resolve(handoff.workingPath, componentPath);
-            const componentBaseName = path_1.default.basename(resolvedComponentPath);
-            const declaration = (0, exports.resolveComponentDeclaration)(resolvedComponentPath, componentBaseName);
-            if (!declaration) {
-                const modernFiles = getModernDeclarationFiles(componentBaseName);
-                const legacyFiles = getLegacyDeclarationFiles(componentBaseName);
-                logger_1.Logger.warn(`Missing config: ${path_1.default.resolve(resolvedComponentPath, [...modernFiles, ...legacyFiles].join(' or '))}`);
-                continue;
-            }
-            const resolvedComponentConfigPath = path_1.default.resolve(resolvedComponentPath, declaration.fileName);
-            configFiles.push(resolvedComponentConfigPath);
-            let component;
-            try {
-                const importedDeclaration = loadDeclarationFile(resolvedComponentConfigPath, handoff.modulePath);
-                const rawComponent = importedDeclaration.default || importedDeclaration;
-                component = (0, declaration_1.normalizeComponentDeclaration)(rawComponent, {
-                    declarationPath: resolvedComponentConfigPath,
-                    fallbackId: componentBaseName,
-                    warn: (message) => logger_1.Logger.warn(message),
-                });
-            }
-            catch (err) {
-                logger_1.Logger.error(`Failed to read or parse config: ${resolvedComponentConfigPath}`, err);
-                continue;
-            }
-            // Initialize options with safe defaults
-            component.options || (component.options = {
-                transformer: { defaults: {}, replace: {} },
+    // A directory's lane depends on what its declaration holds, not on which config key registered
+    // it, so the declaration is loaded before the lane is chosen.
+    for (const itemPath of (0, exports.getCatalogItemDirectories)(handoff.config, handoff.workingPath)) {
+        const itemBaseName = path_1.default.basename(itemPath);
+        const declaration = (0, exports.resolveComponentDeclaration)(itemPath, itemBaseName);
+        if (!declaration) {
+            const declarationFiles = getDeclarationFiles(itemBaseName);
+            logger_1.Logger.warn(`Missing catalog declaration (use .handoff.ts, .handoff.js, or .handoff.cjs; see UPGRADE.md#catalog-items): ${path_1.default.resolve(itemPath, declarationFiles.join(' or '))}`);
+            continue;
+        }
+        const declarationPath = path_1.default.resolve(itemPath, declaration.fileName);
+        const indexKey = (0, path_2.normalizePathForCompare)(declarationPath);
+        configFiles.push(declarationPath);
+        // A declaration can be mid-edit under `start`, so every failure is a warning and the file is
+        // retried on the next save. The index records it with an unknown kind, so a watcher does not
+        // guess the wrong lane.
+        const skip = (message, error) => {
+            // The message carries the authoring error, so it belongs in the warning rather than in a
+            // debug line the default log level hides.
+            const detail = error instanceof Error && error.message ? ` — ${error.message}` : '';
+            logger_1.Logger.warn(`${message}: ${declarationPath}${detail}`);
+            logger_1.Logger.debug('Declaration parse detail:', error);
+            configFileIndex.set(indexKey, { kind: 'unknown', entityId: itemBaseName });
+        };
+        let classified;
+        try {
+            const moduleExports = loadDeclarationFile(declarationPath, handoff.modulePath);
+            classified = (0, catalog_1.normalizeCatalogItem)(moduleExports, {
+                declarationPath,
+                fallbackId: itemBaseName,
+                warn: (message) => logger_1.Logger.warn(message),
             });
-            (_l = component.options).transformer || (_l.transformer = { defaults: {}, replace: {} });
-            const transformer = component.options.transformer;
-            (_g = transformer.cssRootClass) !== null && _g !== void 0 ? _g : (transformer.cssRootClass = null);
-            (_h = transformer.tokenNameSegments) !== null && _h !== void 0 ? _h : (transformer.tokenNameSegments = null);
-            // Normalize keys and values to lowercase
-            transformer.defaults = (0, exports.toLowerCaseKeysAndValues)(Object.assign({}, transformer.defaults));
-            transformer.replace = (0, exports.toLowerCaseKeysAndValues)(Object.assign({}, transformer.replace));
-            // Save transformer config
-            result.options[component.id] = transformer;
-            // Discover CSF stories early so patterns can resolve stories like normal previews.
-            component.previews = discoverCsfPreviews(component, handoff);
-            // Save full component entry
-            result.entries.components[component.id] = component;
-            configFileIndex.set((0, path_2.normalizePathForCompare)(resolvedComponentConfigPath), { kind: 'component', entityId: component.id });
         }
-    }
-    // -------------------------------------------------------------------------
-    // Load pattern declarations
-    // -------------------------------------------------------------------------
-    if ((_k = (_j = handoff.config.entries) === null || _j === void 0 ? void 0 : _j.patterns) === null || _k === void 0 ? void 0 : _k.length) {
-        const patternPaths = handoff.config.entries.patterns.flatMap(exports.getItemsForPath);
-        for (const patternPath of patternPaths) {
-            const resolvedPatternPath = path_1.default.resolve(handoff.workingPath, patternPath);
-            const patternBaseName = path_1.default.basename(resolvedPatternPath);
-            const declaration = (0, exports.resolveComponentDeclaration)(resolvedPatternPath, patternBaseName);
-            if (!declaration) {
-                const modernFiles = getModernDeclarationFiles(patternBaseName);
-                const legacyFiles = getLegacyDeclarationFiles(patternBaseName);
-                logger_1.Logger.warn(`Missing pattern config: ${path_1.default.resolve(resolvedPatternPath, [...modernFiles, ...legacyFiles].join(' or '))}`);
-                continue;
-            }
-            const resolvedPatternConfigPath = path_1.default.resolve(resolvedPatternPath, declaration.fileName);
-            configFiles.push(resolvedPatternConfigPath);
-            let pattern;
-            try {
-                const importedDeclaration = loadDeclarationFile(resolvedPatternConfigPath, handoff.modulePath);
-                const rawPattern = importedDeclaration.default || importedDeclaration;
-                pattern = (0, pattern_1.normalizePatternDeclaration)(rawPattern, {
-                    declarationPath: resolvedPatternConfigPath,
-                    fallbackId: patternBaseName,
-                });
-            }
-            catch (err) {
-                // Treat as a warning rather than an error: the file may be empty or
-                // mid-edit. It is already tracked in configFiles above, so
-                // watchRuntimeConfiguration will pick it up once the file is saved
-                // with valid content.
-                logger_1.Logger.warn(`Pattern config skipped (incomplete or invalid) — will retry on next save: ${resolvedPatternConfigPath}`);
-                logger_1.Logger.debug(`Pattern parse detail:`, err);
-                continue;
-            }
-            configFileIndex.set((0, path_2.normalizePathForCompare)(resolvedPatternConfigPath), { kind: 'pattern', entityId: pattern.id });
-            result.entries.patterns[pattern.id] = pattern;
+        catch (err) {
+            skip('Declaration skipped (incomplete or invalid) — will retry on next save', err);
+            continue;
         }
+        const takenBy = declaredIds.get(classified.item.id);
+        if (takenBy) {
+            logger_1.Logger.warn(`Catalog id "${classified.item.id}" is already declared by ${takenBy}. Skipping ${declarationPath}. ` +
+                `Give each catalog item a unique id.`);
+            result.duplicateCatalogIds.push({ id: classified.item.id, kept: takenBy, skipped: declarationPath });
+            // An unknown kind makes the watcher skip a rebuild. Any other kind rebuilds the item that owns the id.
+            configFileIndex.set(indexKey, { kind: 'unknown', entityId: classified.item.id });
+            continue;
+        }
+        declaredIds.set(classified.item.id, declarationPath);
+        if (classified.kind === 'pattern') {
+            const pattern = classified.item;
+            configFileIndex.set(indexKey, { kind: 'pattern', entityId: pattern.id });
+            result.entities.patterns[pattern.id] = pattern;
+            continue;
+        }
+        const component = classified.item;
+        // Initialize options with safe defaults
+        component.options || (component.options = {
+            transformer: { defaults: {}, replace: {} },
+        });
+        (_g = component.options).transformer || (_g.transformer = { defaults: {}, replace: {} });
+        const transformer = component.options.transformer;
+        (_e = transformer.cssRootClass) !== null && _e !== void 0 ? _e : (transformer.cssRootClass = null);
+        (_f = transformer.tokenNameSegments) !== null && _f !== void 0 ? _f : (transformer.tokenNameSegments = null);
+        // Normalize keys and values to lowercase
+        transformer.defaults = (0, exports.toLowerCaseKeysAndValues)(Object.assign({}, transformer.defaults));
+        transformer.replace = (0, exports.toLowerCaseKeysAndValues)(Object.assign({}, transformer.replace));
+        // Save transformer config
+        result.options[component.id] = transformer;
+        // Discover CSF stories early so compositions can resolve stories like normal previews.
+        component.previews = discoverCsfPreviews(component, handoff);
+        resolveCsfComponentSource(component);
+        // Save full component entry
+        result.entities.components[component.id] = component;
+        configFileIndex.set(indexKey, { kind: 'component', entityId: component.id });
     }
     // -------------------------------------------------------------------------
     // Discover markdown pages
@@ -252,7 +259,7 @@ const initRuntimeConfig = (handoff) => {
             const { data: frontmatter } = (0, markdown_1.parseMarkdown)(fs_extra_1.default.readFileSync(sourcePath, 'utf-8'));
             const routePath = slug === content_kinds_1.HOME_PAGE_ID ? content_kinds_1.HOME_PAGE_PATH : `/${slug}`;
             const page = (0, page_1.normalizePageDeclaration)(frontmatter, { id: slug, routePath, sourcePath });
-            result.entries.pages[page.id] = page;
+            result.entities.pages[page.id] = page;
         }
         catch (err) {
             logger_1.Logger.warn(`Page skipped (unreadable or invalid frontmatter): ${sourcePath}`);
@@ -268,7 +275,7 @@ const initRuntimeConfig = (handoff) => {
 exports.initRuntimeConfig = initRuntimeConfig;
 /**
  * True when `searchPath` is itself a single component directory: it holds a declaration file named
- * after the directory (`{dirname}.handoff.*`, or a legacy `{dirname}.{json,js,cjs}`). This is what
+ * with a .handoff.ts, .handoff.js, or .handoff.cjs suffix. This is what
  * separates a declared component from a collection directory.
  */
 const isComponentDirectory = (searchPath) => !!(0, exports.resolveComponentDeclaration)(searchPath, path_1.default.basename(searchPath));
@@ -301,14 +308,6 @@ const getComponentsForPath = (searchPath) => {
     return [searchPath];
 };
 exports.getComponentsForPath = getComponentsForPath;
-/**
- * Generic directory discovery for both components and patterns.
- * Reuses the same logic as getComponentsForPath.
- */
-const getItemsForPath = (searchPath) => {
-    return (0, exports.getComponentsForPath)(searchPath);
-};
-exports.getItemsForPath = getItemsForPath;
 /**
  * After both components and patterns are loaded, this function iterates all
  * pattern component refs and auto-registers synthetic preview entries on the
@@ -316,30 +315,32 @@ exports.getItemsForPath = getItemsForPath;
  *
  * This ensures the component build renders every preview needed by patterns
  * so that pattern composition is purely file I/O (no rendering).
+ *
+ * A ref that does not resolve records its reason in `unresolvedReason`. Nothing is logged here.
+ * Discovery runs for every command, and only the pattern build knows whether a ref is skipped or
+ * composed from a fallback. `buildPattern` reports it.
  */
 const injectPatternPreviews = (result) => {
-    var _a, _b, _c, _d, _e, _f;
-    const patterns = (_b = (_a = result.entries) === null || _a === void 0 ? void 0 : _a.patterns) !== null && _b !== void 0 ? _b : {};
-    const components = (_d = (_c = result.entries) === null || _c === void 0 ? void 0 : _c.components) !== null && _d !== void 0 ? _d : {};
+    var _a, _b;
+    const patterns = result.entities.patterns;
+    const components = result.entities.components;
     for (const [patternId, pattern] of Object.entries(patterns)) {
         for (let i = 0; i < pattern.components.length; i++) {
             const ref = pattern.components[i];
             const component = components[ref.id];
             if (!component) {
-                const error = `Pattern "${patternId}" references component "${ref.id}" which is not declared. This fragment will be skipped.`;
-                logger_1.Logger.warn(error);
                 ref.resolved = false;
+                ref.unresolvedReason = `component "${ref.id}" is not declared`;
                 continue;
             }
             // Case 1: only preview, no args -> use the existing preview as-is
             if (ref.preview && !ref.args) {
-                if ((_e = component.previews) === null || _e === void 0 ? void 0 : _e[ref.preview]) {
+                if ((_a = component.previews) === null || _a === void 0 ? void 0 : _a[ref.preview]) {
                     ref.resolved = true;
                 }
                 else {
-                    const error = `Pattern "${patternId}" references preview "${ref.preview}" on component "${ref.id}" which does not exist. This fragment may be skipped.`;
-                    logger_1.Logger.warn(error);
                     ref.resolved = false;
+                    ref.unresolvedReason = `preview "${ref.preview}" of component "${ref.id}" is not declared`;
                 }
                 ref.resolvedPreview = ref.preview;
                 continue;
@@ -353,22 +354,21 @@ const injectPatternPreviews = (result) => {
                     ref.resolved = true;
                 }
                 else {
-                    logger_1.Logger.warn(`Pattern "${patternId}" component ref "${ref.id}" has neither "preview" nor "args", and the component has no previews. This fragment will be skipped.`);
                     ref.resolved = false;
+                    ref.unresolvedReason = `component "${ref.id}" has no previews, and the ref names no "preview" or "args"`;
                 }
                 continue;
             }
             // Case 3: args present (with or without preview base) -> create synthetic preview
             let resolvedValues = {};
             if (ref.preview) {
-                const basePreview = (_f = component.previews) === null || _f === void 0 ? void 0 : _f[ref.preview];
+                const basePreview = (_b = component.previews) === null || _b === void 0 ? void 0 : _b[ref.preview];
                 if (basePreview) {
                     resolvedValues = Object.assign({}, basePreview.values);
                 }
                 else {
-                    const error = `Pattern "${patternId}" references preview "${ref.preview}" on component "${ref.id}" which does not exist. Using args only.`;
-                    logger_1.Logger.warn(error);
                     ref.resolved = false;
+                    ref.unresolvedReason = `preview "${ref.preview}" of component "${ref.id}" is not declared, so only "args" were used`;
                 }
             }
             resolvedValues = Object.assign(Object.assign({}, resolvedValues), ref.args);

package/dist/handlebars.d.ts

@@ -0,0 +1,9 @@
+import type { CatalogItem, CatalogItemMeta } from './catalog/types';
+export type { CatalogItem, CatalogItemMeta, CatalogPreview, CompositionRef, Preview, SourceDescriptor } from './catalog/types';
+/**
+ * Declares a Handlebars catalog item. `implementation` is the path to its `.hbs` template. The
+ * renderer comes from this module, so the build fails an item whose file does not match it.
+ */
+export declare const defineCatalogItem: <TArgs = Record<string, unknown>>(input: CatalogItemMeta & {
+    implementation: string;
+}) => CatalogItem<TArgs>;

package/dist/handlebars.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defineCatalogItem = void 0;
+/**
+ * Handlebars catalog items.
+ *
+ * A template carries no type information, so arguments default to `Record<string, unknown>`. Pass
+ * an argument type to check previews: `defineCatalogItem<BadgeArgs>`.
+ */
+const define_1 = require("./catalog/define");
+/**
+ * Declares a Handlebars catalog item. `implementation` is the path to its `.hbs` template. The
+ * renderer comes from this module, so the build fails an item whose file does not match it.
+ */
+const defineCatalogItem = (input) => (0, define_1.createCatalogItem)(input, 'handlebars');
+exports.defineCatalogItem = defineCatalogItem;

package/dist/index.d.ts

@@ -90,6 +90,20 @@ declare class Handoff {
      * client never enters the docs app bundle.
      */
     checkout(kind: TransferEntityKind, id?: string | string[]): Promise<Handoff>;
+    /**
+     * Publish the catalog items declared in this connected workspace to the configured remote registry:
+     * every one, or only the named ids. An item takes the component lane or the pattern lane depending
+     * on whether it declares an implementation or a composition, so the lane is resolved from the
+     * workspace rather than named by the caller. One build covers both lanes. The publish module is
+     * loaded lazily so the registry client and build code never enter the docs app bundle.
+     */
+    publishCatalog(id?: string | string[]): Promise<Handoff>;
+    /**
+     * Checkout published catalog items from the connected remote registry into this workspace: every
+     * one, or only the named ids. The lane an item was published into is looked up in the registry.
+     * Mirrors {@link publishCatalog}.
+     */
+    checkoutCatalog(id?: string | string[]): Promise<Handoff>;
     /**
      * Publish design token sets from this connected workspace to the configured remote registry. Runs a
      * fresh token build (Figma extract + style transformers), discovers the logical sets, and uploads
@@ -140,7 +154,6 @@ declare class Handoff {
     ejectConfig(): Promise<Handoff>;
     ejectPages(): Promise<Handoff>;
     ejectTheme(): Promise<Handoff>;
-    makeTemplate(component: string, state: string): Promise<Handoff>;
     makePage(name: string, parent: string): Promise<Handoff>;
     makeComponent(name: string): Promise<Handoff>;
     start(): Promise<Handoff>;
@@ -215,12 +228,10 @@ declare class Handoff {
      */
     private readJsonFile;
 }
-export type { ComponentObject as Component } from './transformers/preview/types';
 export type { Config, RegisterHandlebarsHelpersContext } from './types/config';
 export { defineConfig } from './config';
-export { defineComponent, defineCsfComponent, defineHandlebarsComponent, definePattern, defineReactComponent, } from './declarations';
+export type { CatalogItem, CatalogItemEntries, CatalogItemInput, CatalogItemMeta, CatalogPreview, CompositionRef, Preview, SourceDescriptor, SourceFormat, RendererKind, } from './catalog';
 export { defineAssetStorage } from './registry/asset-storage/define';
 export type { AssetStorage, AssetStorageContext, AssetStorageFactory, AssetStorageInput, AssetStorageReadResult, } from './registry/asset-storage/types';
-export type { CsfDeclarationConfig, DeclarationPreview, GenericDeclarationConfig, GenericPatternDeclarationConfig, HandlebarsDeclarationConfig, PatternComponentRef, ReactDeclarationConfig, RendererKind, } from './declarations';
 export { Transformers as CoreTransformers, TransformerUtils as CoreTransformerUtils, Types as CoreTypes } from 'handoff-core';
 export default Handoff;