handoff-app 1.1.3 → 1.2.0-1

package/dist/cli/make.js

@@ -148,7 +148,7 @@ const makeComponent = (handoff, name) => __awaiter(void 0, void 0, void 0, funct
     }
     else {
         componentsRoot = path_1.default.resolve(handoff.workingPath, DEFAULT_COMPONENTS_DIR);
-        logger_1.Logger.warn(`No entries.components configured in handoff.config.js. ` +
+        logger_1.Logger.warn(`No entries.components configured in handoff.config.*. ` +
             `Scaffolding into "${DEFAULT_COMPONENTS_DIR}/". ` +
             `Add this path to entries.components in your config so the build picks it up.`);
     }
@@ -168,9 +168,6 @@ const makeComponent = (handoff, name) => __awaiter(void 0, void 0, void 0, funct
     const htmlTemplate = fs_extra_1.default.readFileSync(htmlPath, 'utf8');
     fs_extra_1.default.writeFileSync(targetHtml, htmlTemplate);
     logger_1.Logger.success(`New component ${name}.hbs was created in ${workingPath}`);
-    const jsonpath = path_1.default.resolve(templatePath, 'template.json');
-    const jsonTemplate = fs_extra_1.default.readFileSync(jsonpath, 'utf8');
-    fs_extra_1.default.writeFileSync(path_1.default.resolve(workingPath, `${name}.json`), jsonTemplate);
     const writeJSFile = yield p.confirm({
         message: `Generate a supporting javascript file ${name}.js?`,
         initialValue: false,
@@ -191,6 +188,34 @@ const makeComponent = (handoff, name) => __awaiter(void 0, void 0, void 0, funct
         const scssTemplate = fs_extra_1.default.readFileSync(scssPath, 'utf8');
         fs_extra_1.default.writeFileSync(path_1.default.resolve(workingPath, `${name}.scss`), scssTemplate);
     }
+    const declarationEntries = [`template: './${name}.hbs'`];
+    if (writeJSFile === true) {
+        declarationEntries.push(`js: './${name}.js'`);
+    }
+    if (writeSassFile === true) {
+        declarationEntries.push(`scss: './${name}.scss'`);
+    }
+    const declarationContent = `const { defineHandlebarsComponent } = require('handoff-app');
+
+module.exports = defineHandlebarsComponent({
+  id: '${name}',
+  name: '',
+  description: '',
+  group: '',
+  type: 'element',
+  entries: {
+    ${declarationEntries.join(',\n    ')}
+  },
+  previews: {
+    default: {
+      title: 'Default',
+      args: {}
+    }
+  }
+});
+`;
+    fs_extra_1.default.writeFileSync(path_1.default.resolve(workingPath, `${name}.handoff.js`), declarationContent);
+    logger_1.Logger.success(`New component declaration ${name}.handoff.js was created in ${workingPath}`);
     return handoff;
 });
 exports.makeComponent = makeComponent;

package/dist/cli/scaffold.js

@@ -41,9 +41,8 @@ const chalk_1 = __importDefault(require("chalk"));
 const fs_extra_1 = __importDefault(require("fs-extra"));
 const path_1 = __importDefault(require("path"));
 // Constants
-const CONFIG_FILES = ['handoff.config.json', 'handoff.config.js', 'handoff.config.cjs'];
+const CONFIG_FILES = ['handoff.config.ts', 'handoff.config.js', 'handoff.config.cjs', 'handoff.config.json'];
 const COMPONENTS_DIR = 'components';
-const DEFAULT_VERSION = '1.0.0';
 const DEFAULT_GROUPS = [
     { value: 'Atomic Elements', label: 'Atomic Elements' },
     { value: 'Forms', label: 'Forms' },
@@ -64,25 +63,48 @@ const toTitleCase = (str) => {
  * Generate the component JS stub content
  */
 const generateComponentStub = (config) => {
-    // Build entries object with relative paths to generated files
     const entriesLines = [];
     if (config.generateTsx) {
-        entriesLines.push(`    template: './${config.name}.tsx',`);
+        entriesLines.push(`    component: './${config.name}.tsx',`);
+    }
+    else {
+        entriesLines.push(`    template: './${config.name}.hbs',`);
     }
     if (config.generateScss) {
         entriesLines.push(`    scss: './${config.name}.scss',`);
     }
-    const entriesBlock = entriesLines.length > 0
-        ? `  entries: {\n${entriesLines.join('\n')}\n  },\n`
-        : '';
-    return `/** @type {import('handoff-app').Component} */
-module.exports = {
-  title: "${config.title}",
+    const commonMetadata = `  id: "${config.name}",
+  name: "${config.title}",
   description: "${config.description}",
   group: "${config.group}",
   type: "element",
-  figmaComponentId: "${config.name}",
-${entriesBlock}};
+  figmaComponentId: "${config.name}",`;
+    if (config.generateTsx) {
+        return `const { defineReactComponent } = require('handoff-app');
+const ${toTitleCase(config.name).replace(/\s/g, '')} = require('./${config.name}').default;
+
+module.exports = defineReactComponent(${toTitleCase(config.name).replace(/\s/g, '')}, {
+${commonMetadata}
+  entries: {
+${entriesLines.join('\n')}
+  },
+  previews: {
+    default: { title: "Default", args: {} }
+  }
+});
+`;
+    }
+    return `const { defineHandlebarsComponent } = require('handoff-app');
+
+module.exports = defineHandlebarsComponent({
+${commonMetadata}
+  entries: {
+${entriesLines.join('\n')}
+  },
+  previews: {
+    default: { title: "Default", args: {} }
+  }
+});
 `;
 };
 /**
@@ -236,8 +258,8 @@ const updateConfigFile = (handoff, componentNames) => __awaiter(void 0, void 0,
         yield fs_extra_1.default.writeJSON(configPath, config, { spaces: 2 });
         return { success: true, isJsConfig: false, configPath, skipped: false };
     }
-    // For JS/CJS config files, try to update them programmatically
-    if (configFile.endsWith('.js') || configFile.endsWith('.cjs')) {
+    // For code config files, try to update them programmatically
+    if (configFile.endsWith('.ts') || configFile.endsWith('.js') || configFile.endsWith('.cjs')) {
         try {
             let content = yield fs_extra_1.default.readFile(configPath, 'utf8');
             // Check if entries.components already exists
@@ -281,7 +303,7 @@ const updateConfigFile = (handoff, componentNames) => __awaiter(void 0, void 0,
                 yield fs_extra_1.default.writeFile(configPath, content, 'utf8');
                 return { success: true, isJsConfig: true, configPath, skipped: false };
             }
-            // No entries object, try to add it before the closing of module.exports
+            // No entries object, try to add it before the closing of exported object
             const formattedArray = formatComponentsArray(newComponentPaths);
             const entriesBlock = `  entries: {\n    components: ${formattedArray},\n  },\n`;
             // Try to insert after module.exports = {
@@ -290,6 +312,18 @@ const updateConfigFile = (handoff, componentNames) => __awaiter(void 0, void 0,
                 yield fs_extra_1.default.writeFile(configPath, content, 'utf8');
                 return { success: true, isJsConfig: true, configPath, skipped: false };
             }
+            // Try to insert after export default {
+            if (/export\s+default\s+\{/.test(content)) {
+                content = content.replace(/(export\s+default\s+\{)/, `$1\n${entriesBlock}`);
+                yield fs_extra_1.default.writeFile(configPath, content, 'utf8');
+                return { success: true, isJsConfig: true, configPath, skipped: false };
+            }
+            // Try to insert into defineConfig({ ... })
+            if (/defineConfig\s*\(\s*\{/.test(content)) {
+                content = content.replace(/(defineConfig\s*\(\s*\{)/, `$1\n${entriesBlock}`);
+                yield fs_extra_1.default.writeFile(configPath, content, 'utf8');
+                return { success: true, isJsConfig: true, configPath, skipped: false };
+            }
             // Fallback: couldn't parse the JS config
             return { success: false, isJsConfig: true, configPath, skipped: false };
         }
@@ -304,11 +338,11 @@ const updateConfigFile = (handoff, componentNames) => __awaiter(void 0, void 0,
  */
 const createComponentFiles = (handoff, config) => __awaiter(void 0, void 0, void 0, function* () {
     const createdFiles = [];
-    const componentDir = path_1.default.resolve(handoff.workingPath, COMPONENTS_DIR, config.name, DEFAULT_VERSION);
+    const componentDir = path_1.default.resolve(handoff.workingPath, COMPONENTS_DIR, config.name);
     // Ensure directory exists
     yield fs_extra_1.default.ensureDir(componentDir);
-    // Create the main component JS file
-    const jsPath = path_1.default.join(componentDir, `${config.name}.js`);
+    // Create the main component declaration file
+    const jsPath = path_1.default.join(componentDir, `${config.name}.handoff.js`);
     yield fs_extra_1.default.writeFile(jsPath, generateComponentStub(config));
     createdFiles.push(jsPath);
     // Optionally create TSX file
@@ -317,6 +351,13 @@ const createComponentFiles = (handoff, config) => __awaiter(void 0, void 0, void
         yield fs_extra_1.default.writeFile(tsxPath, generateReactComponentStub(config.name, config.variantProps));
         createdFiles.push(tsxPath);
     }
+    else {
+        const hbsTemplatePath = path_1.default.resolve(handoff.modulePath, 'config/templates/component/template.hbs');
+        const hbsTemplate = yield fs_extra_1.default.readFile(hbsTemplatePath, 'utf8');
+        const hbsPath = path_1.default.join(componentDir, `${config.name}.hbs`);
+        yield fs_extra_1.default.writeFile(hbsPath, hbsTemplate);
+        createdFiles.push(hbsPath);
+    }
     // Optionally create SCSS file
     if (config.generateScss) {
         const scssPath = path_1.default.join(componentDir, `${config.name}.scss`);
@@ -332,7 +373,7 @@ const displayComponentPreview = (config) => {
     const stub = generateComponentStub(config);
     const lines = stub.split('\n');
     const preview = lines.slice(0, 12).join('\n') + '\n  ...\n};';
-    p.note(preview, `Preview: ${config.name}.js`);
+    p.note(preview, `Preview: ${config.name}.handoff.js`);
 };
 /**
  * Main scaffold entry point

package/dist/cli.js

@@ -19,7 +19,7 @@ class HandoffCliError extends Error {
  * Show the help message
  */
 const showVersion = () => {
-    return 'Handoff App - 1.1.3';
+    return 'Handoff App - 1.2.0-1';
 };
 /**
  * Define a CLI error

package/dist/config/helpers.d.ts

@@ -0,0 +1,7 @@
+import { Config } from '../types/config';
+export declare const normalizeConfig: (config: Config) => Config;
+/**
+ * Optional helper for strongly-typed config authoring.
+ * It normalizes modern camelCase keys to legacy runtime keys.
+ */
+export declare const defineConfig: (config: Config) => Config;

package/dist/config/helpers.js

@@ -0,0 +1,31 @@
+"use strict";
+var __rest = (this && this.__rest) || function (s, e) {
+    var t = {};
+    for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)
+        t[p] = s[p];
+    if (s != null && typeof Object.getOwnPropertySymbols === "function")
+        for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) {
+            if (e.indexOf(p[i]) < 0 && Object.prototype.propertyIsEnumerable.call(s, p[i]))
+                t[p[i]] = s[p[i]];
+        }
+    return t;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defineConfig = exports.normalizeConfig = void 0;
+const normalizeAppConfig = (app) => {
+    if (!app)
+        return app;
+    const { googleTagManager, typeCopy, typeSort, colorSort, componentSort, basePath } = app, rest = __rest(app, ["googleTagManager", "typeCopy", "typeSort", "colorSort", "componentSort", "basePath"]);
+    return Object.assign(Object.assign({}, rest), { google_tag_manager: googleTagManager !== null && googleTagManager !== void 0 ? googleTagManager : app.google_tag_manager, type_copy: typeCopy !== null && typeCopy !== void 0 ? typeCopy : app.type_copy, type_sort: typeSort !== null && typeSort !== void 0 ? typeSort : app.type_sort, color_sort: colorSort !== null && colorSort !== void 0 ? colorSort : app.color_sort, component_sort: componentSort !== null && componentSort !== void 0 ? componentSort : app.component_sort, base_path: basePath !== null && basePath !== void 0 ? basePath : app.base_path });
+};
+const normalizeConfig = (config) => {
+    const { devAccessToken, figmaProjectId, assetsZipLinks, app } = config, rest = __rest(config, ["devAccessToken", "figmaProjectId", "assetsZipLinks", "app"]);
+    return Object.assign(Object.assign({}, rest), { dev_access_token: devAccessToken !== null && devAccessToken !== void 0 ? devAccessToken : config.dev_access_token, figma_project_id: figmaProjectId !== null && figmaProjectId !== void 0 ? figmaProjectId : config.figma_project_id, assets_zip_links: assetsZipLinks !== null && assetsZipLinks !== void 0 ? assetsZipLinks : config.assets_zip_links, app: normalizeAppConfig(app) });
+};
+exports.normalizeConfig = normalizeConfig;
+/**
+ * Optional helper for strongly-typed config authoring.
+ * It normalizes modern camelCase keys to legacy runtime keys.
+ */
+const defineConfig = (config) => (0, exports.normalizeConfig)(config);
+exports.defineConfig = defineConfig;

package/dist/config/index.d.ts

@@ -1,5 +1,6 @@
 export { defaultConfig, getClientConfig } from './defaults';
 export type { ImageStyle } from './defaults';
-export { initConfig } from './loader';
+export { initConfig, initConfigWithMetadata } from './loader';
+export { defineConfig } from './helpers';
 export { initRuntimeConfig } from './runtime';
 export { validateConfig } from './validator';

package/dist/config/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.validateConfig = exports.initRuntimeConfig = exports.initConfig = exports.getClientConfig = exports.defaultConfig = void 0;
+exports.validateConfig = exports.initRuntimeConfig = exports.defineConfig = exports.initConfigWithMetadata = exports.initConfig = 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; } });
@@ -8,6 +8,10 @@ Object.defineProperty(exports, "getClientConfig", { enumerable: true, get: funct
 // Config file loading
 var loader_1 = require("./loader");
 Object.defineProperty(exports, "initConfig", { enumerable: true, get: function () { return loader_1.initConfig; } });
+Object.defineProperty(exports, "initConfigWithMetadata", { enumerable: true, get: function () { return loader_1.initConfigWithMetadata; } });
+// Config helpers
+var helpers_1 = require("./helpers");
+Object.defineProperty(exports, "defineConfig", { enumerable: true, get: function () { return helpers_1.defineConfig; } });
 // Runtime config resolution
 var runtime_1 = require("./runtime");
 Object.defineProperty(exports, "initRuntimeConfig", { enumerable: true, get: function () { return runtime_1.initRuntimeConfig; } });

package/dist/config/loader.d.ts

@@ -1,11 +1,20 @@
 import { Config } from '../types/config';
+type ConfigLoadResult = {
+    config: Config;
+    configPath?: string;
+};
+/**
+ * Loads the handoff configuration from the project root and returns metadata.
+ */
+export declare const initConfigWithMetadata: (configOverride?: Partial<Config>) => ConfigLoadResult;
 /**
  * Loads the handoff configuration from the project root.
  *
- * Searches for config files in order: handoff.config.json, handoff.config.js, handoff.config.cjs.
+ * Searches for config files in order: handoff.config.ts, handoff.config.js, handoff.config.cjs, handoff.config.json.
  * Merges file config with any provided overrides, then applies defaults for missing values.
  *
  * @param configOverride - Optional partial config to override file-loaded values.
  * @returns The fully resolved Config object.
  */
 export declare const initConfig: (configOverride?: Partial<Config>) => Config;
+export {};

package/dist/config/loader.js

@@ -3,47 +3,111 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.initConfig = void 0;
+exports.initConfig = exports.initConfigWithMetadata = 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 logger_1 = require("../utils/logger");
 const defaults_1 = require("./defaults");
+const CONFIG_FILE_PREFERENCE = [
+    'handoff.config.ts',
+    'handoff.config.js',
+    'handoff.config.cjs',
+    'handoff.config.json',
+];
+const evaluateTypeScriptConfig = (filePath, handoffModulePath) => {
+    var _a, _b;
+    const buildResult = esbuild_1.default.buildSync({
+        entryPoints: [filePath],
+        bundle: true,
+        write: false,
+        platform: 'node',
+        format: 'cjs',
+        target: 'node16',
+        logLevel: 'silent',
+        external: ['handoff-app'],
+    });
+    const code = (_b = (_a = buildResult.outputFiles) === null || _a === void 0 ? void 0 : _a[0]) === null || _b === void 0 ? void 0 : _b.text;
+    if (!code) {
+        throw new Error(`Unable to compile config file "${filePath}"`);
+    }
+    const mod = { exports: {} };
+    const localRequire = (0, module_1.createRequire)(filePath);
+    const handoffRequire = (0, module_1.createRequire)(path_1.default.resolve(handoffModulePath, 'package.json'));
+    const runtimeRequire = (id) => {
+        try {
+            return localRequire(id);
+        }
+        catch (_a) {
+            return handoffRequire(id);
+        }
+    };
+    const evaluator = new Function('require', 'module', 'exports', '__filename', '__dirname', code);
+    evaluator(runtimeRequire, mod, mod.exports, filePath, path_1.default.dirname(filePath));
+    return mod.exports;
+};
+const loadConfigFile = (configPath) => {
+    if (configPath.endsWith('.json')) {
+        const buffer = fs_extra_1.default.readFileSync(configPath);
+        return JSON.parse(buffer.toString());
+    }
+    if (configPath.endsWith('.ts')) {
+        const handoffModulePath = path_1.default.resolve(__dirname, '../..');
+        const importedConfig = evaluateTypeScriptConfig(configPath, handoffModulePath);
+        return (importedConfig.default || importedConfig);
+    }
+    // Invalidate require cache to ensure fresh read
+    delete require.cache[require.resolve(configPath)];
+    const importedConfig = require(configPath);
+    return (importedConfig.default || importedConfig);
+};
+const resolveConfigFilePath = () => {
+    const existing = CONFIG_FILE_PREFERENCE
+        .map((fileName) => path_1.default.resolve(process.cwd(), fileName))
+        .filter((filePath) => fs_extra_1.default.existsSync(filePath));
+    if (!existing.length) {
+        return { selected: undefined, ignored: [] };
+    }
+    const [selected, ...ignored] = existing;
+    return { selected, ignored };
+};
 /**
- * Loads the handoff configuration from the project root.
- *
- * Searches for config files in order: handoff.config.json, handoff.config.js, handoff.config.cjs.
- * Merges file config with any provided overrides, then applies defaults for missing values.
- *
- * @param configOverride - Optional partial config to override file-loaded values.
- * @returns The fully resolved Config object.
+ * Loads the handoff configuration from the project root and returns metadata.
  */
-const initConfig = (configOverride) => {
+const initConfigWithMetadata = (configOverride) => {
     let config = {};
-    const possibleConfigFiles = ['handoff.config.json', 'handoff.config.js', 'handoff.config.cjs'];
-    // Find the first existing config file
-    const configFile = possibleConfigFiles.find((file) => fs_extra_1.default.existsSync(path_1.default.resolve(process.cwd(), file)));
-    if (configFile) {
-        const configPath = path_1.default.resolve(process.cwd(), configFile);
-        if (configFile.endsWith('.json')) {
-            const defBuffer = fs_extra_1.default.readFileSync(configPath);
-            config = JSON.parse(defBuffer.toString());
-        }
-        else if (configFile.endsWith('.js') || configFile.endsWith('.cjs')) {
-            // Invalidate require cache to ensure fresh read
-            delete require.cache[require.resolve(configPath)];
-            const importedConfig = require(configPath);
-            config = importedConfig.default || importedConfig;
-        }
+    const { selected: configPath, ignored } = resolveConfigFilePath();
+    if (ignored.length > 0 && configPath) {
+        logger_1.Logger.warn(`Multiple config files found. Using "${path_1.default.basename(configPath)}" and ignoring: ${ignored
+            .map((filePath) => `"${path_1.default.basename(filePath)}"`)
+            .join(', ')}.`);
+    }
+    if (configPath) {
+        config = loadConfigFile(configPath);
     }
     // Apply overrides if provided
     if (configOverride) {
-        Object.keys(configOverride).forEach((key) => {
-            const value = configOverride[key];
+        Object.entries(configOverride).forEach(([key, value]) => {
             if (value !== undefined) {
                 config[key] = value;
             }
         });
     }
-    const returnConfig = Object.assign(Object.assign({}, (0, defaults_1.defaultConfig)()), config);
-    return returnConfig;
+    const resolvedConfig = Object.assign(Object.assign({}, (0, defaults_1.defaultConfig)()), config);
+    return { config: resolvedConfig, configPath };
+};
+exports.initConfigWithMetadata = initConfigWithMetadata;
+/**
+ * Loads the handoff configuration from the project root.
+ *
+ * Searches for config files in order: handoff.config.ts, handoff.config.js, handoff.config.cjs, handoff.config.json.
+ * Merges file config with any provided overrides, then applies defaults for missing values.
+ *
+ * @param configOverride - Optional partial config to override file-loaded values.
+ * @returns The fully resolved Config object.
+ */
+const initConfig = (configOverride) => {
+    return (0, exports.initConfigWithMetadata)(configOverride).config;
 };
 exports.initConfig = initConfig;

package/dist/config/normalizers/declaration.d.ts

@@ -0,0 +1,11 @@
+import { RendererKind } from '../../declarations/types';
+import { ComponentListObject } from '../../transformers/preview/types';
+type RawDeclaration = Record<string, any>;
+type NormalizeOptions = {
+    declarationPath: string;
+    fallbackId: string;
+    warn: (message: string) => void;
+};
+export declare const inferRendererFromEntries: (entries?: Record<string, string | undefined>) => RendererKind | undefined;
+export declare const normalizeComponentDeclaration: (raw: RawDeclaration, options: NormalizeOptions) => ComponentListObject;
+export {};

package/dist/config/normalizers/declaration.js

@@ -0,0 +1,119 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeComponentDeclaration = exports.inferRendererFromEntries = void 0;
+const path_1 = __importDefault(require("path"));
+const isCsfStoryFile = (filePath) => {
+    return !!filePath && /\.stories\.(jsx|tsx|js|ts)$/.test(filePath);
+};
+const isReactComponentFile = (filePath) => {
+    return !!filePath && /\.(jsx|tsx)$/.test(filePath) && !isCsfStoryFile(filePath);
+};
+const isHandlebarsFile = (filePath) => {
+    return !!filePath && /\.hbs$/.test(filePath);
+};
+const inferRendererFromEntries = (entries) => {
+    if (!entries)
+        return undefined;
+    if (entries.story || isCsfStoryFile(entries.template)) {
+        return 'csf';
+    }
+    if (entries.component || isReactComponentFile(entries.template)) {
+        return 'react';
+    }
+    if (isHandlebarsFile(entries.template)) {
+        return 'handlebars';
+    }
+    return undefined;
+};
+exports.inferRendererFromEntries = inferRendererFromEntries;
+const resolveEntryPaths = (entries, declarationPath) => {
+    const declarationDir = path_1.default.dirname(declarationPath);
+    const resolved = {};
+    for (const [key, value] of Object.entries(entries)) {
+        if (!value)
+            continue;
+        resolved[key] = path_1.default.resolve(declarationDir, value);
+    }
+    return resolved;
+};
+const normalizePreviews = (previews, declarationPath, warn) => {
+    if (!previews)
+        return previews;
+    const normalized = Object.assign({}, previews);
+    for (const [previewName, previewValue] of Object.entries(previews)) {
+        if (!previewValue || typeof previewValue !== 'object')
+            continue;
+        const preview = Object.assign({}, previewValue);
+        if (preview.args !== undefined) {
+            if (preview.values !== undefined) {
+                warn(`Preview "${previewName}" in "${declarationPath}" defines both "args" and "values". Using "args".`);
+            }
+            preview.values = preview.args;
+            delete preview.args;
+        }
+        normalized[previewName] = preview;
+    }
+    return normalized;
+};
+const normalizeBestPracticeFields = (raw, declarationPath, warn) => {
+    const normalized = Object.assign({}, raw);
+    const hasCamelShouldDo = normalized.shouldDo !== undefined;
+    const hasSnakeShouldDo = normalized.should_do !== undefined;
+    const hasCamelShouldNotDo = normalized.shouldNotDo !== undefined;
+    const hasSnakeShouldNotDo = normalized.should_not_do !== undefined;
+    if (hasCamelShouldDo && hasSnakeShouldDo) {
+        warn(`"${declarationPath}" defines both "shouldDo" and "should_do". Using "shouldDo".`);
+    }
+    if (hasCamelShouldNotDo && hasSnakeShouldNotDo) {
+        warn(`"${declarationPath}" defines both "shouldNotDo" and "should_not_do". Using "shouldNotDo".`);
+    }
+    if (hasCamelShouldDo) {
+        normalized.should_do = normalized.shouldDo;
+    }
+    if (hasCamelShouldNotDo) {
+        normalized.should_not_do = normalized.shouldNotDo;
+    }
+    if (!hasCamelShouldDo && hasSnakeShouldDo) {
+        normalized.shouldDo = normalized.should_do;
+    }
+    if (!hasCamelShouldNotDo && hasSnakeShouldNotDo) {
+        normalized.shouldNotDo = normalized.should_not_do;
+    }
+    return normalized;
+};
+const normalizeComponentDeclaration = (raw, options) => {
+    const normalizedRaw = normalizeBestPracticeFields(Object.assign({}, raw), options.declarationPath, options.warn);
+    const entries = resolveEntryPaths(Object.assign({}, (normalizedRaw.entries || {})), options.declarationPath);
+    const resolvedRenderer = normalizedRaw.renderer || (0, exports.inferRendererFromEntries)(entries);
+    if (resolvedRenderer === 'react') {
+        const componentPath = entries.component || entries.template;
+        if (!componentPath) {
+            throw new Error(`Component "${options.fallbackId}" in "${options.declarationPath}" uses renderer "react" but is missing entries.component`);
+        }
+        entries.component = componentPath;
+        entries.template = componentPath;
+    }
+    if (resolvedRenderer === 'csf') {
+        const storyPath = entries.story || entries.template;
+        if (!storyPath) {
+            throw new Error(`Component "${options.fallbackId}" in "${options.declarationPath}" uses renderer "csf" but is missing entries.story`);
+        }
+        entries.story = storyPath;
+        entries.template = storyPath;
+    }
+    if (resolvedRenderer === 'handlebars') {
+        if (!entries.template) {
+            throw new Error(`Component "${options.fallbackId}" in "${options.declarationPath}" uses renderer "handlebars" but is missing entries.template`);
+        }
+    }
+    if (normalizedRaw.page && normalizedRaw.page.slices && !Array.isArray(normalizedRaw.page.slices)) {
+        throw new Error(`Component "${options.fallbackId}" in "${options.declarationPath}" has invalid page.slices; expected an array.`);
+    }
+    const normalizedPreviews = normalizePreviews(normalizedRaw.previews, options.declarationPath, options.warn);
+    const explicitId = typeof normalizedRaw.id === 'string' && normalizedRaw.id.trim().length > 0 ? normalizedRaw.id.trim() : undefined;
+    return Object.assign(Object.assign({}, normalizedRaw), { id: explicitId || options.fallbackId, title: normalizedRaw.name || normalizedRaw.title || '', renderer: resolvedRenderer, entries, previews: normalizedPreviews });
+};
+exports.normalizeComponentDeclaration = normalizeComponentDeclaration;

package/dist/config/normalizers/pattern.d.ts

@@ -0,0 +1,8 @@
+import { PatternListObject } from '../../transformers/preview/types';
+type RawPatternDeclaration = Record<string, any>;
+type NormalizePatternOptions = {
+    declarationPath: string;
+    fallbackId: string;
+};
+export declare const normalizePatternDeclaration: (raw: RawPatternDeclaration, options: NormalizePatternOptions) => PatternListObject;
+export {};

package/dist/config/normalizers/pattern.js

@@ -0,0 +1,35 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizePatternDeclaration = void 0;
+const normalizePatternDeclaration = (raw, options) => {
+    if (!raw.name || typeof raw.name !== 'string') {
+        throw new Error(`Pattern "${options.fallbackId}" in "${options.declarationPath}" is missing a required "name" field.`);
+    }
+    if (!Array.isArray(raw.components) || raw.components.length === 0) {
+        throw new Error(`Pattern "${options.fallbackId}" in "${options.declarationPath}" must define a non-empty "components" array.`);
+    }
+    const components = raw.components.map((ref, index) => {
+        if (!ref || typeof ref.id !== 'string' || ref.id.trim().length === 0) {
+            throw new Error(`Pattern "${options.fallbackId}" in "${options.declarationPath}" has an invalid component reference at index ${index}: missing "id".`);
+        }
+        const preview = typeof ref.preview === 'string' ? ref.preview.trim() : undefined;
+        return {
+            id: ref.id.trim(),
+            preview,
+            args: ref.args && typeof ref.args === 'object' ? Object.assign({}, ref.args) : undefined,
+        };
+    });
+    const explicitId = typeof raw.id === 'string' && raw.id.trim().length > 0
+        ? raw.id.trim()
+        : undefined;
+    return {
+        id: explicitId || options.fallbackId,
+        title: raw.name,
+        description: typeof raw.description === 'string' ? raw.description : undefined,
+        group: typeof raw.group === 'string' ? raw.group : undefined,
+        tags: Array.isArray(raw.tags) ? raw.tags.filter((t) => typeof t === 'string') : undefined,
+        components,
+        path: '',
+    };
+};
+exports.normalizePatternDeclaration = normalizePatternDeclaration;

package/dist/config/runtime.d.ts

@@ -1,4 +1,4 @@
-import { Config, RuntimeConfig } from '../types/config';
+import { Config, ConfigFileEntry, RuntimeConfig } from '../types/config';
 /**
  * Handoff instance shape needed by initRuntimeConfig.
  * Avoids importing the full Handoff class to prevent circular deps.
@@ -6,15 +6,16 @@ import { Config, RuntimeConfig } from '../types/config';
 interface HandoffContext {
     config: Config;
     workingPath: string;
+    modulePath: string;
 }
 /**
  * Initializes the runtime configuration by resolving component entries,
  * SCSS/JS paths, and transformer options from the handoff config.
  *
  * @param handoff - Object with config and workingPath.
- * @returns A tuple of [RuntimeConfig, configFilePaths].
+ * @returns A tuple of [RuntimeConfig, configFilePaths, configFileIndex].
  */
-export declare const initRuntimeConfig: (handoff: HandoffContext) => [runtimeConfig: RuntimeConfig, configs: string[]];
+export declare const initRuntimeConfig: (handoff: HandoffContext) => [runtimeConfig: RuntimeConfig, configs: string[], configFileIndex: Map<string, ConfigFileEntry>];
 /**
  * Returns a list of component directories for a given path.
  *
@@ -29,6 +30,11 @@ export declare const initRuntimeConfig: (handoff: HandoffContext) => [runtimeCon
  * @returns An array of string paths to 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.
  */