handoff-app 2.0.0-6 → 2.0.0-8

package/dist/app-builder/build.js

@@ -377,13 +377,21 @@ After migrations and deployment, open \`/install\` immediately and create the in
 The installer verifies the deployment but never changes the schema. An exposed, uninstalled registry
 can be claimed by its first visitor, so do not leave this step unattended.
 
-Once installation completes, sign in and authorize a workspace:
+Once installation completes, sign in and authorize a workspace. Either approve the CLI in the
+browser:
 
 \`\`\`bash
 handoff-app login --url https://registry.example.com
 \`\`\`
 
-The browser approval issues a revocable, user-owned credential. The former
+or create a token under Account > Access tokens and set it in the workspace environment:
+
+\`\`\`bash
+HANDOFF_REGISTRY_URL=https://registry.example.com
+HANDOFF_REGISTRY_ACCESS_TOKEN=hnd_…
+\`\`\`
+
+Both produce the same revocable, user-owned credential. The former
 \`HANDOFF_REGISTRY_API_TOKEN\` fixed server secret is no longer accepted.
 
 ## Run it (self-hosting)
@@ -695,14 +703,12 @@ const watchApp = (handoff) => __awaiter(void 0, void 0, void 0, function* () {
         pendingHandlers: new Map(),
         runtimeComponentsWatcher: null,
         runtimeConfigurationWatcher: null,
-        componentDirectoriesWatcher: null,
-        patternDirectoriesWatcher: null,
+        catalogDirectoriesWatcher: null,
     };
     (0, watchers_1.watchPublicDirectory)(handoff, wss, state, chokidarConfig);
     (0, watchers_1.watchRuntimeComponents)(handoff, state, (0, watchers_1.getRuntimeComponentsPathsToWatch)(handoff));
     (0, watchers_1.watchRuntimeConfiguration)(handoff, state);
-    (0, watchers_1.watchComponentDirectories)(handoff, state, chokidarConfig);
-    (0, watchers_1.watchPatternDirectories)(handoff, state, chokidarConfig);
+    (0, watchers_1.watchCatalogDirectories)(handoff, state, chokidarConfig);
     (0, watchers_1.watchGlobalEntries)(handoff, state, chokidarConfig);
     (0, watchers_1.watchPages)(handoff, chokidarConfig);
 });

package/dist/app-builder/client-config.js

@@ -95,7 +95,9 @@ const persistClientConfig = (handoff_1, ...args_1) => __awaiter(void 0, [handoff
     // even when packaged from a connected project. Otherwise a workspace is connected whenever a
     // registry URL resolves — from config/env or a saved device login — so `login` alone surfaces
     // the publish/checkout UI without also requiring HANDOFF_REGISTRY_URL.
-    const connected = mode === 'registry' ? false : Boolean((yield (0, connection_1.resolveAuthenticatedRegistryConnection)(handoff.config, handoff.workingPath)).url);
+    const connected = mode === 'registry'
+        ? false
+        : Boolean((yield (0, connection_1.resolveAuthenticatedRegistryConnection)(handoff.config, handoff.workingPath, handoff.getProfile())).url);
     clientConfig.runtime = Object.assign(Object.assign({}, clientConfig.runtime), { mode, connected });
     yield fs_extra_1.default.writeJson(path_1.default.resolve(appPath, 'client.config.json'), { config: clientConfig }, { spaces: 2 });
     yield fs_extra_1.default.writeJson(path_1.default.resolve(appPath, 'runtime.server.json'), buildServerRuntimeConfig(handoff.config, options.runtimeModeOverride), { spaces: 2 });

package/dist/app-builder/config-diff/strategies/pattern.js

@@ -43,12 +43,12 @@ const snapshot_1 = require("../snapshot");
  * components. Outer key is component id, inner key is synthetic preview key.
  */
 const snapshotPatternSynthetics = (handoff, patternId) => {
-    var _a, _b, _c, _d;
-    const components = (_c = (_b = (_a = handoff.runtimeConfig) === null || _a === void 0 ? void 0 : _a.entries) === null || _b === void 0 ? void 0 : _b.components) !== null && _c !== void 0 ? _c : {};
+    var _a, _b, _c;
+    const components = (_b = (_a = handoff.runtimeConfig) === null || _a === void 0 ? void 0 : _a.entities.components) !== null && _b !== void 0 ? _b : {};
     const prefix = `__pattern_${patternId}_`;
     const result = new Map();
     for (const [componentId, component] of Object.entries(components)) {
-        const previews = (_d = component.internalPatternPreviews) !== null && _d !== void 0 ? _d : {};
+        const previews = (_c = component.internalPatternPreviews) !== null && _c !== void 0 ? _c : {};
         const entries = new Map();
         for (const [key, preview] of Object.entries(previews)) {
             if (key.startsWith(prefix)) {

package/dist/app-builder/watchers/component.js

@@ -23,11 +23,11 @@ const mapEntryTypeToSegment = (type) => {
 };
 exports.mapEntryTypeToSegment = mapEntryTypeToSegment;
 const resolveComponentIdForChangedFile = (handoff, changedFilePath) => {
-    var _a, _b, _c, _d;
+    var _a, _b, _c;
     const normalizedChangedPath = (0, path_2.normalizePathForCompare)(changedFilePath);
-    const runtimeComponents = (_c = (_b = (_a = handoff.runtimeConfig) === null || _a === void 0 ? void 0 : _a.entries) === null || _b === void 0 ? void 0 : _b.components) !== null && _c !== void 0 ? _c : {};
+    const runtimeComponents = (_b = (_a = handoff.runtimeConfig) === null || _a === void 0 ? void 0 : _a.entities.components) !== null && _b !== void 0 ? _b : {};
     for (const [componentId, componentDef] of Object.entries(runtimeComponents)) {
-        const entries = (_d = componentDef.entries) !== null && _d !== void 0 ? _d : {};
+        const entries = (_c = componentDef.entries) !== null && _c !== void 0 ? _c : {};
         for (const entryPath of Object.values(entries)) {
             if (!entryPath)
                 continue;
@@ -49,8 +49,8 @@ exports.resolveComponentIdForChangedFile = resolveComponentIdForChangedFile;
 const getRuntimeComponentsPathsToWatch = (handoff) => {
     var _a, _b, _c;
     const result = new Map();
-    for (const runtimeComponentId of Object.keys((_b = (_a = handoff.runtimeConfig) === null || _a === void 0 ? void 0 : _a.entries.components) !== null && _b !== void 0 ? _b : {})) {
-        const runtimeComponent = handoff.runtimeConfig.entries.components[runtimeComponentId];
+    for (const runtimeComponentId of Object.keys((_b = (_a = handoff.runtimeConfig) === null || _a === void 0 ? void 0 : _a.entities.components) !== null && _b !== void 0 ? _b : {})) {
+        const runtimeComponent = handoff.runtimeConfig.entities.components[runtimeComponentId];
         for (const [runtimeComponentEntryType, runtimeComponentEntryPath] of Object.entries((_c = runtimeComponent.entries) !== null && _c !== void 0 ? _c : {})) {
             const normalizedComponentEntryPath = runtimeComponentEntryPath;
             if (fs_extra_1.default.existsSync(normalizedComponentEntryPath)) {

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

@@ -4,9 +4,8 @@ export interface WatcherState {
     pendingHandlers: Map<string, () => Promise<void>>;
     runtimeComponentsWatcher: chokidar.FSWatcher | null;
     runtimeConfigurationWatcher: chokidar.FSWatcher | null;
-    componentDirectoriesWatcher: chokidar.FSWatcher | null;
-    /** Watches entries.patterns parent directories for newly created pattern subdirectories. */
-    patternDirectoriesWatcher: chokidar.FSWatcher | null;
+    /** Watches every registered catalog directory for newly created item subdirectories. */
+    catalogDirectoriesWatcher: chokidar.FSWatcher | null;
 }
 /**
  * Schedules a handler for execution with mutual exclusion and per-source

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);
@@ -264,18 +264,40 @@ const watchRuntimeConfiguration = (handoff, state) => {
                             const entryBefore = handoff.getConfigFileEntry(changedFile);
                             const strategy = entryBefore ? (0, config_diff_1.getStrategy)(entryBefore.kind) : undefined;
                             const handle = entryBefore && strategy ? strategy.capture(handoff, entryBefore.entityId) : undefined;
-                            handoff.reload();
-                            yield (0, client_config_1.persistClientConfig)(handoff);
+                            let reloadFailed = false;
+                            try {
+                                handoff.reload();
+                                yield (0, client_config_1.persistClientConfig)(handoff);
+                            }
+                            catch (e) {
+                                // A failed reload leaves the last config that loaded on the instance, so the
+                                // re-arm below still names the file that just broke. Without it the file drops
+                                // out of the watch set - chokidar stops tracking a watched file once it is
+                                // deleted - and a later valid save is never seen.
+                                reloadFailed = true;
+                                logger_1.Logger.error('Error reloading runtime configuration:', e);
+                            }
                             (0, exports.watchRuntimeComponents)(handoff, state, (0, component_1.getRuntimeComponentsPathsToWatch)(handoff));
                             (0, exports.watchRuntimeConfiguration)(handoff, state);
+                            if (reloadFailed) {
+                                return;
+                            }
                             const entryAfter = handoff.getConfigFileEntry(changedFile);
-                            const normalizedChanged = (0, path_2.normalizePathForCompare)(changedFile);
-                            const normalizedMainConfig = handoff.getMainConfigFilePath()
-                                ? (0, path_2.normalizePathForCompare)(handoff.getMainConfigFilePath())
-                                : undefined;
-                            if (normalizedMainConfig && normalizedChanged === normalizedMainConfig) {
+                            const kindChanged = !!entryBefore && !!entryAfter && entryBefore.kind !== entryAfter.kind;
+                            if (handoff.isMainConfigFile(changedFile)) {
                                 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 +341,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 +362,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 +402,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

@@ -35,7 +35,11 @@ const CACHE_VERSION = '1.0.0';
  * Gets the path to the build cache file
  */
 function getCachePath(handoff) {
-    return path_1.default.resolve(handoff.modulePath, '.handoff', handoff.getProjectId(), '.cache', 'build-cache.json');
+    // Two profiles share one project id and can build different output, so the profile has to name
+    // the cache file. One shared cache would serve the other profile's components.
+    const profile = handoff.getProfile();
+    const fileName = profile ? `build-cache.${profile}.json` : 'build-cache.json';
+    return path_1.default.resolve(handoff.modulePath, '.handoff', handoff.getProjectId(), '.cache', fileName);
 }
 /**
  * Loads the build cache from disk
@@ -136,14 +140,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 +179,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 +188,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 +208,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 +216,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 +280,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;