handoff-app 2.0.0-5 → 2.0.0-7

package/dist/app-builder/watchers.d.ts

@@ -36,19 +36,12 @@ export declare const watchRuntimeComponents: (handoff: Handoff, state: WatcherSt
  */
 export declare const watchRuntimeConfiguration: (handoff: Handoff, state: WatcherState) => void;
 /**
- * Watches the parent component directories from config.entries.components for
- * new components being added. When a new config file appears in a new
- * subdirectory, reloads the runtime config, restarts the component and
- * configuration watchers, then builds the new component and any patterns that
- * reference it.
- */
-export declare const watchComponentDirectories: (handoff: Handoff, state: WatcherState, chokidarConfig: chokidar.WatchOptions) => void;
-/**
- * Watches the parent pattern directories from config.entries.patterns for new
- * patterns being added. The rebuild sequence intentionally differs from
- * watchComponentDirectories because the dependency arrow is reversed: a new
- * pattern references existing components, so we rebuild only the preview
- * segment of those components (to produce the __pattern_* HTML files that
- * injectPatternPreviews registered) before composing the pattern itself.
+ * Watches `catalog.include` directories for a new item. A single watcher covers implementations
+ * and compositions; the declaration determines which pipeline builds the item.
+ *
+ * The rebuild differs by kind, and the dependency arrow is reversed between them. A new item with
+ * an implementation builds itself, then the compositions that reference it. A new composition
+ * rebuilds the preview segment of the items it references, so the synthetic `__pattern_*` HTML
+ * exists, and only then composes itself.
  */
-export declare const watchPatternDirectories: (handoff: Handoff, state: WatcherState, chokidarConfig: chokidar.WatchOptions) => void;
+export declare const watchCatalogDirectories: (handoff: Handoff, state: WatcherState, chokidarConfig: chokidar.WatchOptions) => void;

package/dist/app-builder/watchers.js

@@ -35,7 +35,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.watchPatternDirectories = exports.watchComponentDirectories = exports.watchRuntimeConfiguration = exports.watchRuntimeComponents = exports.watchGlobalEntries = exports.watchPages = exports.watchAppSource = exports.watchPublicDirectory = exports.mapEntryTypeToSegment = exports.getRuntimeComponentsPathsToWatch = void 0;
+exports.watchCatalogDirectories = exports.watchRuntimeConfiguration = exports.watchRuntimeComponents = exports.watchGlobalEntries = exports.watchPages = exports.watchAppSource = exports.watchPublicDirectory = exports.mapEntryTypeToSegment = exports.getRuntimeComponentsPathsToWatch = void 0;
 const chokidar_1 = __importDefault(require("chokidar"));
 const fs_extra_1 = __importDefault(require("fs-extra"));
 const path_1 = __importDefault(require("path"));
@@ -228,9 +228,9 @@ const watchRuntimeComponents = (handoff, state, runtimeComponentPathsToWatch) =>
 };
 exports.watchRuntimeComponents = watchRuntimeComponents;
 const rebuildPatternComponentPreviews = (handoff, patternId) => __awaiter(void 0, void 0, void 0, function* () {
-    var _a, _b, _c, _d;
-    const pattern = (_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 ? void 0 : _c[patternId];
-    if (!((_d = pattern === null || pattern === void 0 ? void 0 : pattern.components) === null || _d === void 0 ? void 0 : _d.length))
+    var _a, _b;
+    const pattern = (_a = handoff.runtimeConfig) === null || _a === void 0 ? void 0 : _a.entities.patterns[patternId];
+    if (!((_b = pattern === null || pattern === void 0 ? void 0 : pattern.components) === null || _b === void 0 ? void 0 : _b.length))
         return;
     for (const ref of pattern.components) {
         yield (0, builder_1.default)(handoff, ref.id, builder_1.ComponentSegment.Previews);
@@ -273,9 +273,21 @@ const watchRuntimeConfiguration = (handoff, state) => {
                             const normalizedMainConfig = handoff.getMainConfigFilePath()
                                 ? (0, path_2.normalizePathForCompare)(handoff.getMainConfigFilePath())
                                 : undefined;
+                            const kindChanged = !!entryBefore && !!entryAfter && entryBefore.kind !== entryAfter.kind;
                             if (normalizedMainConfig && normalizedChanged === normalizedMainConfig) {
                                 yield (0, builder_1.default)(handoff);
                             }
+                            else if (kindChanged) {
+                                // The declaration switched between an implementation and a composition. A targeted
+                                // rebuild would leave the previous lane's summary entry and artifacts behind, so
+                                // rebuild everything and let the finalizers re-sync.
+                                yield (0, builder_1.default)(handoff);
+                            }
+                            else if ((entryAfter === null || entryAfter === void 0 ? void 0 : entryAfter.kind) === 'unknown') {
+                                // The file did not parse. It stays watched, so the next valid save rebuilds it.
+                                // Guessing a lane here would rebuild the wrong entity.
+                                logger_1.Logger.warn(`Declaration is not valid yet; skipping rebuild: ${changedFile}`);
+                            }
                             else if (handle) {
                                 yield handle.apply(handoff, entryAfter === null || entryAfter === void 0 ? void 0 : entryAfter.entityId);
                             }
@@ -319,9 +331,14 @@ const watchEntityDirectories = (handoff, state, chokidarConfig, options) => {
     if (configPaths.length === 0)
         return;
     const dirsToWatch = [];
+    const seenDirs = new Set();
     for (const configPath of configPaths) {
         const resolved = path_1.default.resolve(handoff.workingPath, configPath);
+        const key = (0, path_2.normalizePathForCompare)(resolved);
+        if (seenDirs.has(key))
+            continue;
         if (fs_extra_1.default.existsSync(resolved) && fs_extra_1.default.statSync(resolved).isDirectory()) {
+            seenDirs.add(key);
             dirsToWatch.push(resolved);
         }
     }
@@ -335,13 +352,8 @@ const watchEntityDirectories = (handoff, state, chokidarConfig, options) => {
     watcher.on('add', (file) => __awaiter(void 0, void 0, void 0, function* () {
         const basename = path_1.default.basename(file);
         const dirName = path_1.default.basename(path_1.default.dirname(file));
-        // Only react to the primary declaration file for the directory (e.g.
-        // button.json, button.js, or button.handoff.ts inside a button/ subdir).
-        // The basename.startsWith(dirName) guard below ensures .ts here only
-        // ever matches files named after their parent directory, not arbitrary
-        // TypeScript source files.
-        const isConfigFile = basename.endsWith('.json') || basename.endsWith('.js') || basename.endsWith('.cjs') || basename.endsWith('.ts');
-        const isNewEntity = isConfigFile && basename.startsWith(dirName) && !knownIds.has(dirName);
+        const isConfigFile = /\.handoff\.(ts|js|cjs)$/.test(basename);
+        const isNewEntity = isConfigFile && !knownIds.has(dirName);
         if (!isNewEntity)
             return;
         yield (0, utils_1.scheduleHandler)(state, `${scheduleKeyPrefix}:${dirName}`, () => __awaiter(void 0, void 0, void 0, function* () {
@@ -380,57 +392,44 @@ const watchEntityDirectories = (handoff, state, chokidarConfig, options) => {
     }));
 };
 /**
- * Watches the parent component directories from config.entries.components for
- * new components being added. When a new config file appears in a new
- * subdirectory, reloads the runtime config, restarts the component and
- * configuration watchers, then builds the new component and any patterns that
- * reference it.
+ * Watches `catalog.include` directories for a new item. A single watcher covers implementations
+ * and compositions; the declaration determines which pipeline builds the item.
+ *
+ * The rebuild differs by kind, and the dependency arrow is reversed between them. A new item with
+ * an implementation builds itself, then the compositions that reference it. A new composition
+ * rebuilds the preview segment of the items it references, so the synthetic `__pattern_*` HTML
+ * exists, and only then composes itself.
  */
-const watchComponentDirectories = (handoff, state, chokidarConfig) => {
+const watchCatalogDirectories = (handoff, state, chokidarConfig) => {
     watchEntityDirectories(handoff, state, chokidarConfig, {
-        getConfigPaths: (h) => { var _a, _b; return (_b = (_a = h.config.entries) === null || _a === void 0 ? void 0 : _a.components) !== null && _b !== void 0 ? _b : []; },
-        getKnownIds: (h) => { var _a, _b, _c; return Object.keys((_c = (_b = (_a = h.runtimeConfig) === null || _a === void 0 ? void 0 : _a.entries) === null || _b === void 0 ? void 0 : _b.components) !== null && _c !== void 0 ? _c : {}); },
-        getWatcher: (s) => s.componentDirectoriesWatcher,
-        setWatcher: (s, w) => { s.componentDirectoriesWatcher = w; },
-        scheduleKeyPrefix: 'newComponent',
-        entityLabel: 'component',
+        getConfigPaths: (h) => { var _a, _b; return [...((_b = (_a = h.config.catalog) === null || _a === void 0 ? void 0 : _a.include) !== null && _b !== void 0 ? _b : [])]; },
+        getKnownIds: (h) => {
+            var _a, _b, _c, _d;
+            return [
+                ...Object.keys((_b = (_a = h.runtimeConfig) === null || _a === void 0 ? void 0 : _a.entities.components) !== null && _b !== void 0 ? _b : {}),
+                ...Object.keys((_d = (_c = h.runtimeConfig) === null || _c === void 0 ? void 0 : _c.entities.patterns) !== null && _d !== void 0 ? _d : {}),
+            ];
+        },
+        getWatcher: (s) => s.catalogDirectoriesWatcher,
+        setWatcher: (s, w) => {
+            s.catalogDirectoriesWatcher = w;
+        },
+        scheduleKeyPrefix: 'newCatalogItem',
+        entityLabel: 'catalog item',
         onDetected: (handoff_1, _a) => __awaiter(void 0, [handoff_1, _a], void 0, function* (handoff, { addedIds }) {
-            for (const componentId of addedIds) {
+            const addedComponentIds = addedIds.filter((id) => { var _a; return !!((_a = handoff.runtimeConfig) === null || _a === void 0 ? void 0 : _a.entities.components[id]); });
+            const addedPatternIds = addedIds.filter((id) => { var _a; return !!((_a = handoff.runtimeConfig) === null || _a === void 0 ? void 0 : _a.entities.patterns[id]); });
+            for (const componentId of addedComponentIds) {
                 yield (0, builder_1.default)(handoff, componentId);
                 yield (0, config_diff_1.runAllFinalizers)(handoff, { patternRebuildComponentIds: [componentId] });
             }
-        }),
-    });
-};
-exports.watchComponentDirectories = watchComponentDirectories;
-/**
- * Watches the parent pattern directories from config.entries.patterns for new
- * patterns being added. The rebuild sequence intentionally differs from
- * watchComponentDirectories because the dependency arrow is reversed: a new
- * pattern references existing components, so we rebuild only the preview
- * segment of those components (to produce the __pattern_* HTML files that
- * injectPatternPreviews registered) before composing the pattern itself.
- */
-const watchPatternDirectories = (handoff, state, chokidarConfig) => {
-    watchEntityDirectories(handoff, state, chokidarConfig, {
-        getConfigPaths: (h) => { var _a, _b; return (_b = (_a = h.config.entries) === null || _a === void 0 ? void 0 : _a.patterns) !== null && _b !== void 0 ? _b : []; },
-        getKnownIds: (h) => { var _a, _b, _c; return Object.keys((_c = (_b = (_a = h.runtimeConfig) === null || _a === void 0 ? void 0 : _a.entries) === null || _b === void 0 ? void 0 : _b.patterns) !== null && _c !== void 0 ? _c : {}); },
-        getWatcher: (s) => s.patternDirectoriesWatcher,
-        setWatcher: (s, w) => { s.patternDirectoriesWatcher = w; },
-        scheduleKeyPrefix: 'newPattern',
-        entityLabel: 'pattern',
-        onDetected: (handoff_1, _a) => __awaiter(void 0, [handoff_1, _a], void 0, function* (handoff, { addedIds }) {
-            // Rebuild only the previews segment for each component the new pattern
-            // references. Their JS/CSS/structure are unchanged — only the new
-            // synthetic preview HTML files need to be generated so that buildPatterns
-            // can assemble the pattern from them.
-            for (const patternId of addedIds) {
+            for (const patternId of addedPatternIds) {
                 yield rebuildPatternComponentPreviews(handoff, patternId);
             }
-            // Build only the new pattern directly rather than going through
-            // runAllFinalizers, which would rebuild all patterns unnecessarily.
-            yield (0, patterns_1.buildPatterns)(handoff, { onlyPatternIds: new Set(addedIds) });
+            if (addedPatternIds.length > 0) {
+                yield (0, patterns_1.buildPatterns)(handoff, { onlyPatternIds: new Set(addedPatternIds) });
+            }
         }),
     });
 };
-exports.watchPatternDirectories = watchPatternDirectories;
+exports.watchCatalogDirectories = watchCatalogDirectories;

package/dist/cache/build-cache.js

@@ -136,14 +136,20 @@ function haveGlobalDepsChanged(cached, current) {
  * Gets all file paths that should be tracked for a component
  */
 function getComponentFilePaths(handoff, componentId) {
-    var _a, _b, _c, _d, _e, _f, _g;
-    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, _b, _c, _d;
+    const runtimeComponent = (_a = handoff.runtimeConfig) === null || _a === void 0 ? void 0 : _a.entities.components[componentId];
     if (!runtimeComponent) {
         return { files: [] };
     }
     const files = [];
     let templateDir;
     const componentDirs = new Set();
+    // A catalog item declares its previews in the declaration file, and its implementation can sit
+    // outside the item directory. The directories derived from `entries` below can therefore miss the
+    // declaration, which would leave a preview edit uncached.
+    if (runtimeComponent.path) {
+        componentDirs.add((0, path_2.normalizePathForCompare)(runtimeComponent.path));
+    }
     // Add entry files and infer component directories from resolved entry paths
     const entries = runtimeComponent.entries;
     if (entries) {
@@ -169,7 +175,7 @@ function getComponentFilePaths(handoff, componentId) {
                     componentDirs.add((0, path_2.normalizePathForCompare)(path_1.default.dirname(templatePath)));
                 }
             }
-            catch (_h) {
+            catch (_e) {
                 // File doesn't exist, still add to track
                 files.push(templatePath);
                 componentDirs.add((0, path_2.normalizePathForCompare)(path_1.default.dirname(templatePath)));
@@ -178,19 +184,9 @@ function getComponentFilePaths(handoff, componentId) {
     }
     // Find the config file path for this component using exact config filename + directory matching.
     const configPaths = handoff.getConfigFilePaths();
-    const expectedConfigFileNames = new Set([
-        `${componentId}.handoff.ts`,
-        `${componentId}.handoff.js`,
-        `${componentId}.handoff.cjs`,
-        `${componentId}.handoff.json`,
-        `${componentId}.json`,
-        `${componentId}.js`,
-        `${componentId}.cjs`,
-    ]);
     const matchingConfigPath = configPaths.find((configPath) => {
         const configFileName = path_1.default.basename(configPath);
-        const isModernDeclaration = /\.handoff\.(ts|js|cjs|json)$/.test(configFileName);
-        if (!expectedConfigFileNames.has(configFileName) && !isModernDeclaration) {
+        if (!/\.handoff\.(ts|js|cjs)$/.test(configFileName)) {
             return false;
         }
         if (componentDirs.size === 0) {
@@ -208,7 +204,7 @@ function getComponentFilePaths(handoff, componentId) {
     // what processComponents must render. Without tracking these files here, the
     // cache would incorrectly consider the component unchanged and skip the preview
     // rebuild, leaving buildPatterns unable to find the required HTML fragments.
-    const runtimePatterns = (_f = (_e = (_d = handoff.runtimeConfig) === null || _d === void 0 ? void 0 : _d.entries) === null || _e === void 0 ? void 0 : _e.patterns) !== null && _f !== void 0 ? _f : {};
+    const runtimePatterns = (_c = (_b = handoff.runtimeConfig) === null || _b === void 0 ? void 0 : _b.entities.patterns) !== null && _c !== void 0 ? _c : {};
     for (const configPath of configPaths) {
         const entry = handoff.getConfigFileEntry(configPath);
         if ((entry === null || entry === void 0 ? void 0 : entry.kind) !== 'pattern')
@@ -216,7 +212,7 @@ function getComponentFilePaths(handoff, componentId) {
         const pattern = runtimePatterns[entry.entityId];
         if (!pattern)
             continue;
-        if ((_g = pattern.components) === null || _g === void 0 ? void 0 : _g.some((ref) => ref.id === componentId)) {
+        if ((_d = pattern.components) === null || _d === void 0 ? void 0 : _d.some((ref) => ref.id === componentId)) {
             files.push(configPath);
         }
     }
@@ -280,24 +276,24 @@ function hasComponentChanged(cached, current) {
  */
 function checkOutputExists(handoff, componentId) {
     return __awaiter(this, void 0, void 0, function* () {
-        var _a, _b, _c, _d, _e, _f;
+        var _a, _b, _c, _d;
         const outputDirectory = path_1.default.resolve(handoff.workingPath, 'public/api/component');
         const componentPath = path_1.default.resolve(outputDirectory, `${componentId}.json`);
         if (!(yield fs_extra_1.default.pathExists(componentPath))) {
             return false;
         }
-        const runtimeComponent = (_c = (_b = (_a = handoff.runtimeConfig) === null || _a === void 0 ? void 0 : _a.entries) === null || _b === void 0 ? void 0 : _b.components) === null || _c === void 0 ? void 0 : _c[componentId];
+        const runtimeComponent = (_a = handoff.runtimeConfig) === null || _a === void 0 ? void 0 : _a.entities.components[componentId];
         const previewIds = new Set([
-            ...Object.keys((_d = runtimeComponent === null || runtimeComponent === void 0 ? void 0 : runtimeComponent.previews) !== null && _d !== void 0 ? _d : {}),
-            ...Object.keys((_e = runtimeComponent === null || runtimeComponent === void 0 ? void 0 : runtimeComponent.internalPatternPreviews) !== null && _e !== void 0 ? _e : {}),
+            ...Object.keys((_b = runtimeComponent === null || runtimeComponent === void 0 ? void 0 : runtimeComponent.previews) !== null && _b !== void 0 ? _b : {}),
+            ...Object.keys((_c = runtimeComponent === null || runtimeComponent === void 0 ? void 0 : runtimeComponent.internalPatternPreviews) !== null && _c !== void 0 ? _c : {}),
         ]);
         try {
             const component = yield fs_extra_1.default.readJson(componentPath);
-            for (const previewId of Object.keys((_f = component === null || component === void 0 ? void 0 : component.previews) !== null && _f !== void 0 ? _f : {})) {
+            for (const previewId of Object.keys((_d = component === null || component === void 0 ? void 0 : component.previews) !== null && _d !== void 0 ? _d : {})) {
                 previewIds.add(previewId);
             }
         }
-        catch (_g) {
+        catch (_e) {
             return false;
         }
         for (const previewId of previewIds) {

package/dist/catalog/define.d.ts

@@ -0,0 +1,6 @@
+import { type RendererKind } from './renderers';
+import type { CatalogItem, CatalogItemInput } from './types';
+/** Keeps declarations as plain data that the loader can read without evaluating Handoff. */
+export declare const createCatalogItem: <TArgs = Record<string, unknown>>(input: CatalogItemInput, renderer?: RendererKind) => CatalogItem<TArgs>;
+/** Validate module declarations too, because JavaScript callers have no compile-time checks. */
+export declare function validateCatalogItem(value: unknown): asserts value is CatalogItem;

package/dist/catalog/define.js

@@ -0,0 +1,72 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createCatalogItem = void 0;
+exports.validateCatalogItem = validateCatalogItem;
+const renderers_1 = require("./renderers");
+const MISSING_RENDERER_HELP = "An implementation needs a renderer. Import defineCatalogItem from 'handoff-app/react' or 'handoff-app/handlebars'.";
+/** Handles the shared implementation forms here so renderer entry points only supply types and a renderer. */
+const stampImplementation = (implementation, renderer) => {
+    if (typeof implementation === 'string') {
+        return { renderer, file: implementation };
+    }
+    const descriptor = implementation;
+    if (descriptor && typeof descriptor === 'object' && typeof descriptor.format === 'string' && typeof descriptor.file === 'string') {
+        return { renderer, format: descriptor.format, file: descriptor.file };
+    }
+    return { renderer, value: implementation };
+};
+/** Keeps declarations as plain data that the loader can read without evaluating Handoff. */
+const createCatalogItem = (input, renderer) => {
+    const hasImplementation = input.implementation !== undefined && input.implementation !== null;
+    const hasComposition = Array.isArray(input.composition) && input.composition.length > 0;
+    if (hasImplementation && hasComposition) {
+        throw new Error('A catalog item declares either "implementation" or "composition", not both.');
+    }
+    if (!hasImplementation && !hasComposition) {
+        throw new Error('A catalog item must declare "implementation" or "composition".');
+    }
+    if (!hasImplementation) {
+        validateCatalogItem(input);
+        return input;
+    }
+    if (!renderer) {
+        throw new Error(MISSING_RENDERER_HELP);
+    }
+    const item = Object.assign(Object.assign({}, input), { implementation: stampImplementation(input.implementation, renderer) });
+    validateCatalogItem(item);
+    return item;
+};
+exports.createCatalogItem = createCatalogItem;
+/** Validate module declarations too, because JavaScript callers have no compile-time checks. */
+function validateCatalogItem(value) {
+    const help = ' Use defineCatalogItem. See UPGRADE.md#catalog-items.';
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new Error('Invalid catalog item.' + help);
+    const item = value;
+    for (const key of ['previews', 'components', 'renderer', 'sourceFormat', 'should_do', 'should_not_do', 'title']) {
+        if (key in item)
+            throw new Error(`Catalog field "${key}" is no longer supported.` + help);
+    }
+    for (const key of ['component', 'story', 'template']) {
+        if (item.entries && key in item.entries)
+            throw new Error(`entries.${key} was removed. Use implementation.` + help);
+    }
+    if (item.composition !== undefined) {
+        if (item.implementation !== undefined || !Array.isArray(item.composition) || !item.composition.length) {
+            throw new Error('Declare either an implementation or a non-empty composition.' + help);
+        }
+        for (const ref of item.composition) {
+            if (!ref || typeof ref.ref !== 'string' || !ref.ref.trim() || 'id' in ref) {
+                throw new Error('Composition members require "ref", the catalog item id.' + help);
+            }
+        }
+        return;
+    }
+    const source = item.implementation;
+    if (!source || !(0, renderers_1.isRendererKind)(source.renderer))
+        throw new Error('implementation must state a supported renderer.' + help);
+    if (source.format !== undefined &&
+        (!(0, renderers_1.isSourceFormat)(source.format) || !renderers_1.SOURCE_FORMATS[source.format].renderers.includes(source.renderer))) {
+        throw new Error('implementation.format is not supported by this renderer.' + help);
+    }
+}

package/dist/catalog/implementation.d.ts

@@ -0,0 +1,27 @@
+/** A source file plus the export the implementation is bound to. */
+export type ResolvedSource = {
+    file: string;
+    /** `default`, a named export, or `*` for a namespace import. */
+    exportName: string;
+};
+/**
+ * Resolves a relative module specifier to a file. Node and bundlers probe extensions and index
+ * files; `path.resolve` alone does not. A bare specifier (a package, or a tsconfig path alias) is
+ * not resolvable against the workspace, so it returns undefined.
+ */
+export declare const resolveModulePath: (specifier: string, fromFile: string) => string | undefined;
+/**
+ * Resolves the value a property is bound to back to its source file.
+ *
+ * Two callers use this: `implementation:` inside a catalog declaration, and `component:` inside a
+ * CSF meta object. In both cases only the value is authored, so the file has to be recovered from
+ * the import that produced it.
+ */
+export declare const resolvePropertySource: (sourcePath: string, property: string) => ResolvedSource | undefined;
+/**
+ * Last-resort lookup when the import cannot be resolved: the single component file sitting next to
+ * the declaration. Story files and the declaration itself are excluded.
+ */
+export declare const findSiblingComponentFile: (directory: string, declarationPath: string) => string | undefined;
+/** True when `file` sits inside `directory`. Publish rejects any path that escapes the entity directory. */
+export declare const isInsideDirectory: (file: string, directory: string) => boolean;

package/dist/catalog/implementation.js

@@ -0,0 +1,133 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isInsideDirectory = exports.findSiblingComponentFile = exports.resolvePropertySource = exports.resolveModulePath = void 0;
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const path_1 = __importDefault(require("path"));
+const CANDIDATE_EXTENSIONS = ['.tsx', '.jsx', '.ts', '.js', '.mjs', '.cjs'];
+const isStoryFile = (filePath) => /\.stories\.(jsx|tsx|js|ts)$/.test(filePath);
+/**
+ * Resolves a relative module specifier to a file. Node and bundlers probe extensions and index
+ * files; `path.resolve` alone does not. A bare specifier (a package, or a tsconfig path alias) is
+ * not resolvable against the workspace, so it returns undefined.
+ */
+const resolveModulePath = (specifier, fromFile) => {
+    if (!specifier.startsWith('.') && !path_1.default.isAbsolute(specifier))
+        return undefined;
+    const base = path_1.default.resolve(path_1.default.dirname(fromFile), specifier);
+    if (fs_extra_1.default.existsSync(base) && fs_extra_1.default.statSync(base).isFile())
+        return base;
+    for (const extension of CANDIDATE_EXTENSIONS) {
+        const candidate = `${base}${extension}`;
+        if (fs_extra_1.default.existsSync(candidate))
+            return candidate;
+    }
+    for (const extension of CANDIDATE_EXTENSIONS) {
+        const candidate = path_1.default.join(base, `index${extension}`);
+        if (fs_extra_1.default.existsSync(candidate))
+            return candidate;
+    }
+    return undefined;
+};
+exports.resolveModulePath = resolveModulePath;
+/** Reads the identifier a property is bound to, e.g. `implementation: Button` or `component: UI.Card`. */
+const readPropertyIdentifier = (sourceCode, property) => {
+    const match = sourceCode.match(new RegExp(`\\b${property}\\s*:\\s*([A-Za-z_$][\\w$]*(?:\\.[A-Za-z_$][\\w$]*)*)\\s*(?![\\w$(])`));
+    return match === null || match === void 0 ? void 0 : match[1];
+};
+/** Finds which export of an import clause is bound to `localName`. */
+const matchImportClause = (clause, localName) => {
+    const namespaceMatch = clause.match(/\*\s+as\s+([A-Za-z_$][\w$]*)/);
+    if ((namespaceMatch === null || namespaceMatch === void 0 ? void 0 : namespaceMatch[1]) === localName)
+        return '*';
+    const bracesMatch = clause.match(/\{([\s\S]*)\}/);
+    if (bracesMatch) {
+        for (const rawSpecifier of bracesMatch[1].split(',')) {
+            const specifier = rawSpecifier.trim().replace(/^type\s+/, '');
+            if (!specifier)
+                continue;
+            const aliased = specifier.match(/^([A-Za-z_$][\w$]*)\s+as\s+([A-Za-z_$][\w$]*)$/);
+            if (aliased) {
+                if (aliased[2] === localName)
+                    return aliased[1];
+                continue;
+            }
+            if (specifier === localName)
+                return specifier;
+        }
+    }
+    const defaultBinding = clause.split(',')[0].trim();
+    if (/^[A-Za-z_$][\w$]*$/.test(defaultBinding) && defaultBinding === localName)
+        return 'default';
+    return undefined;
+};
+const findBinding = (sourceCode, localName) => {
+    var _a;
+    for (const match of sourceCode.matchAll(/import\s+([\s\S]*?)\s+from\s*['"]([^'"]+)['"]/g)) {
+        const exportName = matchImportClause(match[1].trim(), localName);
+        if (exportName)
+            return { specifier: match[2], exportName };
+    }
+    const requireBinding = sourceCode.match(new RegExp(`(?:const|let|var)\\s+${localName}\\s*=\\s*require\\(\\s*['"]([^'"]+)['"]\\s*\\)(?:\\.([A-Za-z_$][\\w$]*))?`));
+    if (requireBinding) {
+        return { specifier: requireBinding[1], exportName: (_a = requireBinding[2]) !== null && _a !== void 0 ? _a : '*' };
+    }
+    const requireNamed = sourceCode.match(new RegExp(`(?:const|let|var)\\s*\\{[^}]*\\b${localName}\\b[^}]*\\}\\s*=\\s*require\\(\\s*['"]([^'"]+)['"]\\s*\\)`));
+    if (requireNamed) {
+        return { specifier: requireNamed[1], exportName: localName };
+    }
+    return undefined;
+};
+/**
+ * Resolves the value a property is bound to back to its source file.
+ *
+ * Two callers use this: `implementation:` inside a catalog declaration, and `component:` inside a
+ * CSF meta object. In both cases only the value is authored, so the file has to be recovered from
+ * the import that produced it.
+ */
+const resolvePropertySource = (sourcePath, property) => {
+    let sourceCode;
+    try {
+        sourceCode = fs_extra_1.default.readFileSync(sourcePath, 'utf8');
+    }
+    catch (_a) {
+        return undefined;
+    }
+    const identifier = readPropertyIdentifier(sourceCode, property);
+    if (!identifier)
+        return undefined;
+    const [localName, ...memberPath] = identifier.split('.');
+    const binding = findBinding(sourceCode, localName);
+    if (!binding)
+        return undefined;
+    const file = (0, exports.resolveModulePath)(binding.specifier, sourcePath);
+    if (!file)
+        return undefined;
+    // `UI.Button` names the export directly; a namespace import on its own has no single export.
+    const exportName = memberPath.length ? memberPath[memberPath.length - 1] : binding.exportName;
+    return { file, exportName: exportName === '*' ? 'default' : exportName };
+};
+exports.resolvePropertySource = resolvePropertySource;
+/**
+ * Last-resort lookup when the import cannot be resolved: the single component file sitting next to
+ * the declaration. Story files and the declaration itself are excluded.
+ */
+const findSiblingComponentFile = (directory, declarationPath) => {
+    if (!fs_extra_1.default.existsSync(directory))
+        return undefined;
+    const candidates = fs_extra_1.default
+        .readdirSync(directory)
+        .filter((name) => /\.(tsx|jsx)$/.test(name) && !isStoryFile(name))
+        .map((name) => path_1.default.resolve(directory, name))
+        .filter((file) => file !== path_1.default.resolve(declarationPath));
+    return candidates.length === 1 ? candidates[0] : undefined;
+};
+exports.findSiblingComponentFile = findSiblingComponentFile;
+/** True when `file` sits inside `directory`. Publish rejects any path that escapes the entity directory. */
+const isInsideDirectory = (file, directory) => {
+    const relative = path_1.default.relative(directory, file);
+    return !!relative && !relative.startsWith('..') && !path_1.default.isAbsolute(relative);
+};
+exports.isInsideDirectory = isInsideDirectory;

package/dist/catalog/index.d.ts

@@ -0,0 +1,6 @@
+export { createCatalogItem, validateCatalogItem } from './define';
+export { findSiblingComponentFile, isInsideDirectory, resolveModulePath, resolvePropertySource, type ResolvedSource, } from './implementation';
+export { normalizeCatalogItem, type CatalogNormalizeResult } from './normalize';
+export { entryKeyFor, moduleFor, sourceForFile, type ComponentSource, type EntryKey, type RendererKind, type SourceFormat, } from './renderers';
+export { createCatalogPreviews, orderPreviews, readExportOrder, readExportOrderFromSource } from './previews';
+export type { CatalogItem, CatalogItemEntries, CatalogItemInput, CatalogItemMeta, CatalogPreview, CompositionRef, CsfSource, NormalizedImplementation, Preview, SourceDescriptor, } from './types';

package/dist/catalog/index.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readExportOrderFromSource = exports.readExportOrder = exports.orderPreviews = exports.createCatalogPreviews = exports.sourceForFile = exports.moduleFor = exports.entryKeyFor = exports.normalizeCatalogItem = exports.resolvePropertySource = exports.resolveModulePath = exports.isInsideDirectory = exports.findSiblingComponentFile = exports.validateCatalogItem = exports.createCatalogItem = void 0;
+var define_1 = require("./define");
+Object.defineProperty(exports, "createCatalogItem", { enumerable: true, get: function () { return define_1.createCatalogItem; } });
+Object.defineProperty(exports, "validateCatalogItem", { enumerable: true, get: function () { return define_1.validateCatalogItem; } });
+var implementation_1 = require("./implementation");
+Object.defineProperty(exports, "findSiblingComponentFile", { enumerable: true, get: function () { return implementation_1.findSiblingComponentFile; } });
+Object.defineProperty(exports, "isInsideDirectory", { enumerable: true, get: function () { return implementation_1.isInsideDirectory; } });
+Object.defineProperty(exports, "resolveModulePath", { enumerable: true, get: function () { return implementation_1.resolveModulePath; } });
+Object.defineProperty(exports, "resolvePropertySource", { enumerable: true, get: function () { return implementation_1.resolvePropertySource; } });
+var normalize_1 = require("./normalize");
+Object.defineProperty(exports, "normalizeCatalogItem", { enumerable: true, get: function () { return normalize_1.normalizeCatalogItem; } });
+var renderers_1 = require("./renderers");
+Object.defineProperty(exports, "entryKeyFor", { enumerable: true, get: function () { return renderers_1.entryKeyFor; } });
+Object.defineProperty(exports, "moduleFor", { enumerable: true, get: function () { return renderers_1.moduleFor; } });
+Object.defineProperty(exports, "sourceForFile", { enumerable: true, get: function () { return renderers_1.sourceForFile; } });
+var previews_1 = require("./previews");
+Object.defineProperty(exports, "createCatalogPreviews", { enumerable: true, get: function () { return previews_1.createCatalogPreviews; } });
+Object.defineProperty(exports, "orderPreviews", { enumerable: true, get: function () { return previews_1.orderPreviews; } });
+Object.defineProperty(exports, "readExportOrder", { enumerable: true, get: function () { return previews_1.readExportOrder; } });
+Object.defineProperty(exports, "readExportOrderFromSource", { enumerable: true, get: function () { return previews_1.readExportOrderFromSource; } });

package/dist/catalog/normalize.d.ts

@@ -0,0 +1,16 @@
+import type { ComponentListObject, PatternListObject } from '../transformers/preview/types';
+type NormalizeOptions = {
+    declarationPath: string;
+    fallbackId: string;
+    warn: (message: string) => void;
+};
+export type CatalogNormalizeResult = {
+    kind: 'component';
+    item: ComponentListObject;
+} | {
+    kind: 'pattern';
+    item: PatternListObject;
+};
+/** Maps the authoring contract directly into the runtime read model. */
+export declare const normalizeCatalogItem: (moduleExports: Record<string, unknown>, options: NormalizeOptions) => CatalogNormalizeResult;
+export {};