handoff-app 2.0.0-5 → 2.0.0-7

package/dist/registry/checkout/index.js

@@ -60,11 +60,16 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.checkoutEntities = exports.checkoutEntity = exports.reportPlannedWrites = exports.resolveConnectionOrThrow = exports.CheckoutError = void 0;
+exports.checkoutCatalog = exports.checkoutEntities = exports.checkoutEntity = exports.reportPlannedWrites = exports.resolveConnectionOrThrow = exports.CheckoutError = void 0;
 const p = __importStar(require("@clack/prompts"));
 const fs_extra_1 = __importDefault(require("fs-extra"));
+const esbuild_1 = require("esbuild");
+const lodash_1 = require("lodash");
 const path_1 = __importDefault(require("path"));
-const entries_1 = require("../../config/entries");
+const previews_1 = require("../../catalog/previews");
+const define_1 = require("../../catalog/define");
+const renderers_1 = require("../../catalog/renderers");
+const catalog_include_1 = require("../../config/catalog-include");
 const runtime_1 = require("../../config/runtime");
 const logger_1 = require("../../utils/logger");
 const client_1 = require("../client");
@@ -136,9 +141,9 @@ const describeFetchFailure = (error, kind, id, registryUrl) => {
 const promptForCollectionRoot = (handoff, kind, roots) => __awaiter(void 0, void 0, void 0, function* () {
     const relative = (root) => path_1.default.relative(handoff.workingPath, root) || '.';
     if (handoff.force) {
-        throw new CheckoutError(`Cannot determine where to checkout the ${kind}: entries.${kind}s declares individual ${kind}s under different ` +
-            `directories (${roots.map(relative).join(', ')}). Declare a single collection directory in handoff.config, ` +
-            `or run checkout without --force to choose interactively.`);
+        throw new CheckoutError(`Cannot determine where to checkout the ${kind}: catalog.include declares directories under different ` +
+            `parents (${roots.map(relative).join(', ')}), and none is named "${DEFAULT_ENTITY_DIR[kind]}". Declare a single ` +
+            `collection directory in handoff.config, or run checkout without --force to choose interactively.`);
     }
     const choice = yield p.select({
         message: `Where should the new ${kind} be checked out?`,
@@ -152,14 +157,15 @@ const promptForCollectionRoot = (handoff, kind, roots) => __awaiter(void 0, void
 });
 /**
  * Resolve the collection directory a new entity is cloned into from the configured
- * `entries.{components|patterns}`. Each entry is either a collection directory (used as-is) or a
+ * `catalog.include`. Each entry is either a collection directory (used as-is) or a
  * single declared entity directory, in which case its parent is the collection root so the new
- * entity lands as a sibling rather than nested inside. Different parents mean the config is
- * ambiguous, so we ask the user; with nothing configured we fall back to the default subdir.
+ * entity lands as a sibling rather than nested inside. Different parents are settled by the
+ * conventional directory name for the kind, and only then by asking the user. With nothing
+ * configured we fall back to the default subdir.
  */
 const resolveCollectionRoot = (handoff, kind) => __awaiter(void 0, void 0, void 0, function* () {
-    var _a, _b, _c, _d;
-    const configuredRoots = kind === 'component' ? (_b = (_a = handoff.config) === null || _a === void 0 ? void 0 : _a.entries) === null || _b === void 0 ? void 0 : _b.components : (_d = (_c = handoff.config) === null || _c === void 0 ? void 0 : _c.entries) === null || _d === void 0 ? void 0 : _d.patterns;
+    var _a, _b;
+    const configuredRoots = (_b = (_a = handoff.config) === null || _a === void 0 ? void 0 : _a.catalog) === null || _b === void 0 ? void 0 : _b.include;
     if (!(configuredRoots === null || configuredRoots === void 0 ? void 0 : configuredRoots.length)) {
         return path_1.default.resolve(handoff.workingPath, DEFAULT_ENTITY_DIR[kind]);
     }
@@ -169,7 +175,17 @@ const resolveCollectionRoot = (handoff, kind) => __awaiter(void 0, void 0, void
             return (0, runtime_1.isComponentDirectory)(resolved) ? path_1.default.dirname(resolved) : resolved;
         })),
     ];
-    return roots.length === 1 ? roots[0] : promptForCollectionRoot(handoff, kind, roots);
+    if (roots.length === 1) {
+        return roots[0];
+    }
+    // `catalog.include` is one list for both lanes, so a project that registers `components` and
+    // `patterns` offers two roots for every checkout. Without this, every such project prompts, and a
+    // non-interactive `--force` run fails.
+    const conventional = roots.filter((root) => path_1.default.basename(root) === DEFAULT_ENTITY_DIR[kind]);
+    if (conventional.length === 1) {
+        return conventional[0];
+    }
+    return promptForCollectionRoot(handoff, kind, roots);
 });
 /**
  * Resolve the local directory the entity is written into. An already-checked-out or locally-declared
@@ -200,7 +216,7 @@ const existingDeclarationFormat = (dir) => {
         return undefined;
     }
     const ext = path_1.default.extname(declaration.fileName).slice(1).toLowerCase();
-    return ['ts', 'js', 'cjs', 'json'].includes(ext) ? ext : undefined;
+    return ['ts', 'js', 'cjs'].includes(ext) ? ext : undefined;
 };
 /**
  * Resolve the declaration format: an existing local declaration's extension wins, else the
@@ -222,41 +238,25 @@ const resolveDeclarationFileName = (dir, id, format) => {
     return `${id}.handoff.${format}`;
 };
 const isPlainObject = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
-/**
- * The single authored "primary" entry key per renderer. The normalizer derives the others (e.g. it
- * mirrors a React `component` into `template`, and a CSF `story` into `template`), so the stored
- * record carries duplicates that must not be re-authored. React authors `component`; handlebars and
- * CSF author `template` (a `.stories.*` template is what marks a CSF component).
- */
-const PRIMARY_ENTRY_BY_RENDERER = {
-    react: 'component',
-    handlebars: 'template',
-    csf: 'template',
-};
-/** Primary entry keys, in preference order, for an unknown renderer. */
-const PRIMARY_ENTRY_KEYS = ['component', 'template', 'story'];
 /** Supporting entry keys kept verbatim regardless of renderer. */
 const SUPPORTING_ENTRY_KEYS = ['js', 'scss', 'schema', 'templates'];
 const asString = (value) => (typeof value === 'string' && value ? value : undefined);
 const asStringArray = (value) => Array.isArray(value) && value.every((item) => typeof item === 'string') ? value : undefined;
 /**
- * Rebuild the authored `entries` for a renderer: keep only the renderer's primary entry key (so the
- * normalizer-duplicated keys are dropped) plus the supporting source entries (`js`/`scss`/`schema`/
- * `templates`). An unknown renderer keeps the first available primary key by preference order.
+ * Normalization mirrors React `component` and CSF `story` entries into `template`. Checkout omits these duplicates
+ * and preserves supporting entries (`js`/`scss`/`schema`/`templates`).
  */
-const buildEntries = (entries, renderer) => {
+const buildEntries = (entries, source, options = {}) => {
     if (!isPlainObject(entries)) {
         return undefined;
     }
     const result = {};
-    const primaryKey = renderer ? PRIMARY_ENTRY_BY_RENDERER[renderer] : undefined;
-    if (primaryKey && typeof entries[primaryKey] === 'string') {
-        result[primaryKey] = entries[primaryKey];
-    }
-    else if (!primaryKey) {
-        const fallback = PRIMARY_ENTRY_KEYS.find((key) => typeof entries[key] === 'string');
-        if (fallback) {
-            result[fallback] = entries[fallback];
+    // A catalog item names its implementation through `implementation`, so re-emitting the primary
+    // entry key would state the same fact twice.
+    const primaryKey = (0, renderers_1.entryKeyFor)(source.renderer, source.sourceFormat);
+    if (options.includePrimary !== false) {
+        if (primaryKey && typeof entries[primaryKey] === 'string') {
+            result[primaryKey] = entries[primaryKey];
         }
     }
     for (const key of SUPPORTING_ENTRY_KEYS) {
@@ -267,9 +267,9 @@ const buildEntries = (entries, renderer) => {
     return Object.keys(result).length > 0 ? result : undefined;
 };
 /**
- * Rebuild the authored `previews` map (`DeclarationPreview`) from the stored previews, keeping only
+ * Rebuild the authored preview map from the stored previews, keeping only
  * authored fields (`title`, `args`) and dropping build-derived ones (rendered `url`, `usage`,
- * `sourcePreview`). The component normalizer maps authored `args` to `values`, so the stored record
+ * `sourcePreview`). Catalog normalization maps authored `args` to `values`, so the stored record
  * carries `values`; checkout re-emits it as `args` to match the authoring convention (the form
  * `make`/`scaffold` generate). Both rebuild identically.
  */
@@ -285,7 +285,7 @@ const buildPreviews = (previews) => {
         const preview = {};
         if (typeof raw.title === 'string')
             preview.title = raw.title;
-        const args = raw.args !== undefined ? raw.args : raw.values;
+        const args = raw.values;
         if (args !== undefined)
             preview.args = args;
         result[key] = preview;
@@ -293,7 +293,7 @@ const buildPreviews = (previews) => {
     return Object.keys(result).length > 0 ? result : undefined;
 };
 /**
- * Synthesize an authored component declaration (`GenericDeclarationConfig`) from the normalized
+ * Synthesize an authored component declaration from the normalized
  * record. Only authored fields are kept; registry-/build-derived data (`path`, `image`,
  * `properties`/docgen, rendered preview URLs, `internalPatternPreviews`, `validations`, `variant`,
  * review `metadata`) is dropped so the local build regenerates it. `name` carries the record title
@@ -301,7 +301,7 @@ const buildPreviews = (previews) => {
  * `shouldNotDo` are emitted in their camelCase authored form.
  */
 const buildComponentDeclaration = (item) => {
-    var _a, _b, _c, _d, _e;
+    var _a, _b, _c, _d;
     const declaration = {};
     const id = asString(item.id);
     if (id)
@@ -316,13 +316,21 @@ const buildComponentDeclaration = (item) => {
     const type = asString(item.type);
     if (type)
         declaration.type = type;
-    const renderer = asString(item.renderer);
-    if (renderer)
-        declaration.renderer = renderer;
-    const entries = buildEntries(item.entries, renderer);
+    const source = {
+        renderer: item.renderer,
+        sourceFormat: item.sourceFormat,
+    };
+    if (source.renderer)
+        declaration.renderer = source.renderer;
+    if (source.sourceFormat)
+        declaration.sourceFormat = source.sourceFormat;
+    const componentExport = asString(item.componentExport);
+    if (componentExport)
+        declaration.componentExport = componentExport;
+    const entries = buildEntries(item.entries, source);
     if (entries)
         declaration.entries = entries;
-    const previews = buildPreviews(item.previews);
+    const previews = buildPreviews(isPlainObject(item.previews) ? (0, previews_1.orderPreviews)(item.previews, (_d = asStringArray(item.previewOrder)) !== null && _d !== void 0 ? _d : []) : undefined);
     if (previews)
         declaration.previews = previews;
     const categories = asStringArray(item.categories);
@@ -331,10 +339,10 @@ const buildComponentDeclaration = (item) => {
     const tags = asStringArray(item.tags);
     if (tags)
         declaration.tags = tags;
-    const shouldDo = (_d = asStringArray(item.shouldDo)) !== null && _d !== void 0 ? _d : asStringArray(item.should_do);
+    const shouldDo = asStringArray(item.should_do);
     if (shouldDo)
         declaration.shouldDo = shouldDo;
-    const shouldNotDo = (_e = asStringArray(item.shouldNotDo)) !== null && _e !== void 0 ? _e : asStringArray(item.should_not_do);
+    const shouldNotDo = asStringArray(item.should_not_do);
     if (shouldNotDo)
         declaration.shouldNotDo = shouldNotDo;
     const figma = asString(item.figma);
@@ -350,9 +358,9 @@ const buildComponentDeclaration = (item) => {
     return declaration;
 };
 /**
- * Rebuild the authored pattern component refs (`PatternComponentRef`) from the stored entries,
+ * Rebuild the authored pattern component refs from the stored entries,
  * keeping only `id`/`preview`/`args` and dropping build-time resolution fields (`resolvedPreview`,
- * `resolved`).
+ * `resolved`, `unresolvedReason`).
  */
 const buildPatternComponents = (components) => {
     if (!Array.isArray(components)) {
@@ -372,7 +380,7 @@ const buildPatternComponents = (components) => {
     });
 };
 /**
- * Synthesize an authored pattern declaration (`GenericPatternDeclarationConfig`) from the normalized
+ * Synthesize an authored pattern declaration from the normalized
  * record. Only the authored fields (`id`, `name`, `description`, `group`, `tags`, `components`) are
  * kept; derived fields (`path`, rendered `url`, review `metadata`) are dropped.
  */
@@ -395,35 +403,25 @@ const buildPatternDeclaration = (item) => {
     declaration.components = buildPatternComponents(item.components);
     return declaration;
 };
-/**
- * Pick the renderer-specific `handoff-app` component factory from the record's renderer so the
- * synthesized declaration matches the authored contract for that renderer. `react`/`handlebars`/`csf`
- * each have a dedicated factory that stamps the renderer itself (so the renderer is dropped from the
- * authored config); an unknown/absent renderer falls back to the generic `defineComponent`, which
- * keeps `renderer` in the config.
- */
-const resolveComponentFactory = (renderer) => {
-    switch (renderer) {
-        case 'react':
-            return { name: 'defineReactComponent', stampsRenderer: true };
-        case 'handlebars':
-            return { name: 'defineHandlebarsComponent', stampsRenderer: true };
-        case 'csf':
-            return { name: 'defineCsfComponent', stampsRenderer: true };
-        default:
-            return { name: 'defineComponent', stampsRenderer: false };
-    }
-};
 /** Drop a key from an object without mutating it. */
 const omit = (object, key) => {
     const _a = object, _b = key, _removed = _a[_b], rest = __rest(_a, [typeof _b === "symbol" ? _b : _b + ""]);
     return rest;
 };
+const omitSource = (object) => omit(omit(object, 'renderer'), 'sourceFormat');
 /** Turn a relative entry path into a module specifier (extension stripped, `./`-prefixed). */
 const toImportSpecifier = (entryPath) => {
     const withoutExt = entryPath.replace(COMPONENT_EXTENSION, '').split(path_1.default.sep).join('/');
     return withoutExt.startsWith('.') ? withoutExt : `./${withoutExt}`;
 };
+/**
+ * Turn a relative entry path into a `./`-prefixed file path. Unlike a module specifier this keeps
+ * the extension, because `fromCSF('./Card.stories.tsx')` and a `.hbs` implementation name files.
+ */
+const toFilePath = (entryPath) => {
+    const normalized = entryPath.split(path_1.default.sep).join('/');
+    return normalized.startsWith('.') ? normalized : `./${normalized}`;
+};
 /** Derive a safe PascalCase identifier for the imported React component. */
 const toComponentIdentifier = (entryPath, fallback) => {
     const base = path_1.default.basename(entryPath).replace(COMPONENT_EXTENSION, '');
@@ -438,6 +436,12 @@ const toComponentIdentifier = (entryPath, fallback) => {
 };
 /** Keys matching this are emitted unquoted in JS/TS object literals; others are single-quoted. */
 const JS_IDENTIFIER = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+/** A value emitted verbatim into a literal, such as an imported identifier or a `fromCSF(...)` call. */
+class RawExpression {
+    constructor(code) {
+        this.code = code;
+    }
+}
 /** Serialize a string as a single-quoted JS literal (repo style), escaping safely. */
 const singleQuote = (value) => {
     var _a;
@@ -470,6 +474,9 @@ const singleQuote = (value) => {
 const toJsLiteral = (value, indentLevel = 0) => {
     const pad = '  '.repeat(indentLevel);
     const padInner = '  '.repeat(indentLevel + 1);
+    if (value instanceof RawExpression) {
+        return value.code;
+    }
     if (value === null) {
         return 'null';
     }
@@ -496,53 +503,170 @@ const toJsLiteral = (value, indentLevel = 0) => {
     });
     return `{\n${lines.join(',\n')}\n${pad}}`;
 };
-/** Wrap a config object in a factory call for the given code format (unquoted identifier keys). */
-const wrapFactory = (factory, config, format) => {
-    const literal = toJsLiteral(config);
-    return format === 'ts'
-        ? `import { ${factory} } from 'handoff-app';\n\nexport default ${factory}(${literal});\n`
-        : `const { ${factory} } = require('handoff-app');\n\nmodule.exports = ${factory}(${literal});\n`;
-};
 /**
- * Synthesize the component declaration file. JSON declarations are the bare object (carrying
- * `renderer`/`entries`, which the loader reads directly). Code declarations use the renderer-specific
- * factory; React additionally imports the component from its `entries.component` source and passes it
- * as the factory's first argument (matching the authored `defineReactComponent` contract). When the
- * renderer is `react` but no component entry is available, it falls back to the generic factory.
+ * Re-shape stored previews for the catalog API: the display title becomes `name`, and is omitted
+ * when it matches what `startCase` derives from the export name.
  */
-const renderComponentDeclaration = (declaration, format) => {
+const toCatalogPreviews = (previews) => {
+    if (!previews)
+        return undefined;
+    const result = {};
+    for (const [key, raw] of Object.entries(previews)) {
+        if (!isPlainObject(raw))
+            continue;
+        const preview = {};
+        const title = asString(raw.title);
+        if (title && title !== (0, lodash_1.startCase)(key))
+            preview.name = title;
+        if (raw.args !== undefined)
+            preview.args = raw.args;
+        result[key] = preview;
+    }
+    return result;
+};
+const previewKeysAreIdentifiers = (previews) => !previews || Object.keys(previews).every((key) => JS_IDENTIFIER.test(key));
+const withImplementation = (item, implementation) => {
+    const ordered = {};
+    const placed = new Set(['implementation']);
+    for (const key of ['id', 'name', 'description', 'group']) {
+        if (item[key] !== undefined) {
+            ordered[key] = item[key];
+            placed.add(key);
+        }
+    }
+    ordered.implementation = implementation;
+    for (const [key, value] of Object.entries(item)) {
+        if (!placed.has(key))
+            ordered[key] = value;
+    }
+    return ordered;
+};
+const buildImplementationImport = (declaration, componentEntry, format) => {
     var _a;
-    if (format === 'json') {
-        return `${JSON.stringify(declaration, null, 2)}\n`;
-    }
-    const renderer = asString(declaration.renderer);
-    const factory = resolveComponentFactory(renderer);
-    const componentEntry = isPlainObject(declaration.entries) ? asString(declaration.entries.component) : undefined;
-    if (factory.name === 'defineReactComponent' && componentEntry) {
-        const specifier = toImportSpecifier(componentEntry);
-        const identifier = toComponentIdentifier(componentEntry, (_a = asString(declaration.id)) !== null && _a !== void 0 ? _a : 'Component');
-        const literal = toJsLiteral(omit(declaration, 'renderer'));
+    const specifier = toImportSpecifier(componentEntry);
+    const exportName = asString(declaration.componentExport);
+    const identifier = exportName !== null && exportName !== void 0 ? exportName : toComponentIdentifier(componentEntry, (_a = asString(declaration.id)) !== null && _a !== void 0 ? _a : 'Component');
+    if (format === 'ts') {
+        const clause = exportName ? `{ ${exportName} }` : identifier;
+        return { statement: `import ${clause} from '${specifier}';`, identifier };
+    }
+    const accessor = exportName ? `.${exportName}` : '.default';
+    return { statement: `const ${identifier} = require('${specifier}')${accessor};`, identifier };
+};
+const buildPreviewExports = (previews, format, previewType) => {
+    if (!previews || Object.keys(previews).length === 0) {
+        return '';
+    }
+    const statements = Object.entries(previews).map(([key, preview]) => {
+        const literal = toJsLiteral(preview);
         return format === 'ts'
-            ? `import { defineReactComponent } from 'handoff-app';\nimport ${identifier} from '${specifier}';\n\nexport default defineReactComponent(${identifier}, ${literal});\n`
-            : `const { defineReactComponent } = require('handoff-app');\nconst ${identifier} = require('${specifier}').default;\n\nmodule.exports = defineReactComponent(${identifier}, ${literal});\n`;
-    }
-    // React without a resolvable component entry can't use defineReactComponent; keep renderer and use
-    // the generic factory so the build still infers the renderer.
-    const effective = factory.name === 'defineReactComponent' ? { name: 'defineComponent', stampsRenderer: false } : factory;
-    const config = effective.stampsRenderer ? omit(declaration, 'renderer') : declaration;
-    return wrapFactory(effective.name, config, format);
+            ? `export const ${key} = ${literal}${previewType ? ` satisfies ${previewType}` : ''};`
+            : `exports.${key} = ${literal};`;
+    });
+    return `\n${statements.join('\n\n')}\n`;
 };
-/** Synthesize the pattern declaration file via `definePattern` (or a bare object for JSON). */
-const renderPatternDeclaration = (declaration, format) => {
-    if (format === 'json') {
-        return `${JSON.stringify(declaration, null, 2)}\n`;
+const renderCatalogDeclaration = (options) => {
+    const { format, entryPoint, imports, named, item, previews } = options;
+    const literal = toJsLiteral(item);
+    const hasPreviews = !!previews && Object.keys(previews).length > 0;
+    if (format === 'ts') {
+        const typeImport = hasPreviews ? [...named, 'type Preview'] : named;
+        const head = [`import { ${typeImport.join(', ')} } from '${entryPoint}';`, ...imports].join('\n');
+        if (!hasPreviews) {
+            return `${head}\n\nexport default defineCatalogItem(${literal});\n`;
+        }
+        return (`${head}\n\nconst item = defineCatalogItem(${literal});\n\nexport default item;\n\n` +
+            `type ItemPreview = Preview<typeof item>;\n${buildPreviewExports(previews, format, 'ItemPreview')}`);
     }
-    return wrapFactory('definePattern', declaration, format);
+    const head = [`const { ${named.join(', ')} } = require('${entryPoint}');`, ...imports].join('\n');
+    return `${head}\n\nexports.default = defineCatalogItem(${literal});\n${buildPreviewExports(previews, format)}`;
+};
+/**
+ * How each renderer authors its implementation. A source format claims an item before its renderer,
+ * because a CSF item is also a React item and the React row would claim it first. The maps are
+ * exhaustive, so a new renderer fails to compile until checkout can write its declaration.
+ */
+const FORMAT_DECLARATIONS = {
+    // The story file owns the previews, so the declaration carries none.
+    csf: ({ entry }) => ({
+        entryPoint: (0, renderers_1.moduleFor)('react'),
+        imports: [],
+        named: ['defineCatalogItem', 'fromCSF'],
+        implementation: new RawExpression(`fromCSF('${toFilePath(entry)}')`),
+    }),
+};
+const RENDERER_DECLARATIONS = {
+    handlebars: ({ entry, previews }) => ({
+        entryPoint: (0, renderers_1.moduleFor)('handlebars'),
+        imports: [],
+        named: ['defineCatalogItem'],
+        implementation: toFilePath(entry),
+        previews: toCatalogPreviews(previews),
+    }),
+    react: ({ declaration, entry, format, previews }) => {
+        const { statement, identifier } = buildImplementationImport(declaration, entry, format);
+        return {
+            entryPoint: (0, renderers_1.moduleFor)('react'),
+            imports: [statement],
+            named: ['defineCatalogItem'],
+            implementation: new RawExpression(identifier),
+            previews: toCatalogPreviews(previews),
+        };
+    },
+};
+/** Emit only catalog declarations, with previews as named exports. */
+const renderComponentDeclaration = (declaration, format) => {
+    const source = {
+        renderer: declaration.renderer,
+        sourceFormat: declaration.sourceFormat,
+    };
+    const { renderer, sourceFormat } = source;
+    const previews = isPlainObject(declaration.previews) ? declaration.previews : undefined;
+    const entries = isPlainObject(declaration.entries) ? declaration.entries : undefined;
+    if (!(0, renderers_1.isRendererKind)(renderer) ||
+        (sourceFormat !== undefined && (!(0, renderers_1.isSourceFormat)(sourceFormat) || !renderers_1.SOURCE_FORMATS[sourceFormat].renderers.includes(renderer)))) {
+        throw new CheckoutError(`Catalog item "${declaration.id}" has invalid renderer/source-format metadata. Rebuild and republish it.`);
+    }
+    if (!previewKeysAreIdentifiers(previews) && sourceFormat !== 'csf') {
+        throw new CheckoutError(`Catalog item "${declaration.id}" has preview names that cannot be exported. Rename them and update composition references before publishing.`);
+    }
+    const item = omit(omit(omitSource(declaration), 'previews'), 'componentExport');
+    const supportingEntries = buildEntries(declaration.entries, source, { includePrimary: false });
+    if (supportingEntries)
+        item.entries = supportingEntries;
+    else
+        delete item.entries;
+    const entry = entries ? asString(entries[(0, renderers_1.entryKeyFor)(renderer, sourceFormat)]) : undefined;
+    if (!entry) {
+        throw new CheckoutError(`Catalog item "${declaration.id}" has no valid implementation source. Rebuild and republish it.`);
+    }
+    const build = sourceFormat ? FORMAT_DECLARATIONS[sourceFormat] : RENDERER_DECLARATIONS[renderer];
+    const _a = build({ declaration, entry, format, previews }), { implementation } = _a, parts = __rest(_a, ["implementation"]);
+    return renderCatalogDeclaration(Object.assign(Object.assign({ format }, parts), { item: withImplementation(item, implementation) }));
+};
+/** Synthesize the composition declaration file via `defineCatalogItem`. */
+const renderPatternDeclaration = (declaration, format) => {
+    const { components } = declaration, rest = __rest(declaration, ["components"]);
+    const item = Object.assign(Object.assign({}, rest), { composition: (Array.isArray(components) ? components : []).map((ref) => {
+            const _a = ref, { id } = _a, refRest = __rest(_a, ["id"]);
+            return Object.assign({ ref: id }, refRest);
+        }) });
+    (0, define_1.validateCatalogItem)(item);
+    return renderCatalogDeclaration({ format, entryPoint: 'handoff-app/pattern', imports: [], named: ['defineCatalogItem'], item });
 };
 /** Synthesize the declaration file contents for an entity, faithful to its renderer/kind contract. */
-const synthesizeDeclaration = (kind, item, format) => kind === 'component'
-    ? renderComponentDeclaration(buildComponentDeclaration(item), format)
-    : renderPatternDeclaration(buildPatternDeclaration(item), format);
+const synthesizeDeclaration = (kind, item, format) => {
+    const declaration = kind === 'component'
+        ? renderComponentDeclaration(buildComponentDeclaration(item), format)
+        : renderPatternDeclaration(buildPatternDeclaration(item), format);
+    try {
+        (0, esbuild_1.transformSync)(declaration, { loader: format === 'ts' ? 'ts' : 'js', logLevel: 'silent' });
+    }
+    catch (_a) {
+        throw new CheckoutError(`Catalog item "${item.id}" cannot be exported as ${format}. Use valid, distinct preview and component export names, then republish.`);
+    }
+    return declaration;
+};
 /**
  * Confirm overwriting any local files the checkout would replace. Returns `true` to proceed. With
  * `--force` (or when nothing would be overwritten) it proceeds without prompting; otherwise it asks
@@ -636,7 +760,7 @@ const checkoutSingle = (handoff, kind, id, client, registryUrl) => __awaiter(voi
         throw error;
     }
     // Pages round-trip as a single verbatim `.md` with no declaration synthesis, and aren't
-    // declared in `entries`, so there's nothing to register.
+    // listed in `catalog.include`, so there's nothing to register.
     if (kind === 'page') {
         yield checkoutPage(handoff, id, payload);
         return null;
@@ -653,6 +777,7 @@ const checkoutSingle = (handoff, kind, id, client, registryUrl) => __awaiter(voi
         }
         return { file, absolutePath };
     });
+    const declaration = synthesizeDeclaration(kind, payload.item, format);
     const plannedWrites = [...sourceTargets.map((entry) => entry.absolutePath), declarationPath];
     const conflicts = plannedWrites.filter((file) => fs_extra_1.default.existsSync(file));
     if (handoff.dryRun) {
@@ -669,7 +794,6 @@ const checkoutSingle = (handoff, kind, id, client, registryUrl) => __awaiter(voi
     for (const { file } of sourceTargets) {
         written.push(yield writeSourceFile(targetDir, file));
     }
-    const declaration = synthesizeDeclaration(kind, payload.item, format);
     yield fs_extra_1.default.writeFile(declarationPath, declaration, 'utf8');
     written.push(declarationPath);
     logger_1.Logger.success(`Checked out ${kind} "${id}" into ${path_1.default.relative(handoff.workingPath, targetDir) || '.'} ` +
@@ -677,28 +801,30 @@ const checkoutSingle = (handoff, kind, id, client, registryUrl) => __awaiter(voi
     return targetDir;
 });
 /**
- * Declare freshly checked-out entities in `entries.{components|patterns}` so the workspace build
+ * Declare freshly checked-out entities in `catalog.include` so the workspace build
  * picks them up. Ones already covered by a collection directory load on their own and are left
  * alone; the rest are added to the config automatically. If the config can't be edited (a computed
- * or unusual `entries` array), we print the paths for the user to add so nothing is silently orphaned.
+ * or unusual `include` array), we print the paths for the user to add so nothing is silently orphaned.
  */
 const registerCheckedOut = (handoff, kind, targetDirs) => __awaiter(void 0, void 0, void 0, function* () {
     if (kind === 'page') {
         return;
     }
-    const entryKind = kind === 'component' ? 'components' : 'patterns';
-    const uncovered = targetDirs.filter((dir) => !(0, entries_1.isEntryCovered)(handoff, entryKind, dir));
-    if (uncovered.length === 0) {
+    const kindLabel = kind === 'component' ? 'components' : 'patterns';
+    const unlisted = targetDirs.filter((dir) => !(0, catalog_include_1.isIncluded)(handoff, dir));
+    if (unlisted.length === 0) {
         return;
     }
-    const result = yield (0, entries_1.writeEntries)(handoff, entryKind, uncovered);
+    const result = yield (0, catalog_include_1.addToCatalog)(handoff, unlisted);
     if (result.status === 'added') {
-        const where = result.configPath ? path_1.default.relative(handoff.workingPath, result.configPath) || path_1.default.basename(result.configPath) : 'handoff.config';
-        logger_1.Logger.success(`Updated ${where} with ${result.added.length} ${entryKind} path(s).`);
+        const where = result.configPath
+            ? path_1.default.relative(handoff.workingPath, result.configPath) || path_1.default.basename(result.configPath)
+            : 'handoff.config';
+        logger_1.Logger.success(`Updated ${where} with ${result.added.length} ${kindLabel} path(s).`);
         return;
     }
     const where = result.configPath ? path_1.default.relative(handoff.workingPath, result.configPath) : 'handoff.config';
-    logger_1.Logger.warn(`Could not update ${where} automatically. Add these to entries.${entryKind} manually:`);
+    logger_1.Logger.warn(`Could not update ${where} automatically. Add these to catalog.include manually:`);
     result.pending.forEach((rel) => logger_1.Logger.warn(`  - ${rel}`));
 });
 /**
@@ -714,41 +840,33 @@ const checkoutEntity = (handoff, kind, id) => __awaiter(void 0, void 0, void 0,
     }
 });
 exports.checkoutEntity = checkoutEntity;
-/**
- * Checkout every published component, pattern, or page of the kind into this workspace. Enumerates
- * the registry's published ids, then checks each out through the shared client. A per-entity failure
- * is collected and never aborts the rest; the run throws at the end if any entity failed. Overwrite
- * prompting is per entity (skipped under `--force`).
- */
-const checkoutEntities = (handoff, kind, ids) => __awaiter(void 0, void 0, void 0, function* () {
-    const connection = yield (0, exports.resolveConnectionOrThrow)(handoff);
-    const client = (0, client_1.createRegistryClient)({ baseUrl: connection.url, accessToken: connection.accessToken });
-    let summaries;
+/** List the ids the registry publishes for one kind, naming the registry in a listing failure. */
+const listPublishedIds = (kind, client, registryUrl) => __awaiter(void 0, void 0, void 0, function* () {
     try {
-        summaries = yield client.listEntities(kind);
+        const summaries = yield client.listEntities(kind);
+        return summaries.map((summary) => summary.id);
     }
     catch (error) {
         if (error instanceof client_1.RegistryClientError) {
-            throw new CheckoutError(`Could not list ${kind}s from the registry at ${connection.url}: ${error.message}`);
+            throw new CheckoutError(`Could not list ${kind}s from the registry at ${registryUrl}: ${error.message}`);
         }
         throw error;
     }
-    const published = summaries.map((summary) => summary.id);
-    const { selected: targets, unknown } = (0, selection_1.selectIds)(published, ids);
-    if (unknown.length > 0) {
-        throw new CheckoutError(`No ${kind} named ${unknown.map((id) => `"${id}"`).join(', ')} is published in the registry. ` +
-            `Published ${kind}s: ${published.join(', ') || '(none)'}.`);
-    }
-    if (targets.length === 0) {
-        logger_1.Logger.success(`No ${kind}s are published in the registry; nothing to checkout.`);
-        return;
-    }
+});
+/**
+ * Check out the given ids of one kind and register what landed. The caller selects the ids, because a
+ * catalog run resolves them across both entity lanes before any of them is written.
+ *
+ * A per-entity failure is collected and never aborts the rest. Failures are reported here, and the
+ * count is returned so the caller raises one error for the whole run.
+ */
+const checkoutSelected = (handoff, kind, targets, client, registryUrl) => __awaiter(void 0, void 0, void 0, function* () {
     let checkedOut = 0;
     const failed = [];
     const targetDirs = [];
     for (const id of targets) {
         try {
-            const targetDir = yield checkoutSingle(handoff, kind, id, client, connection.url);
+            const targetDir = yield checkoutSingle(handoff, kind, id, client, registryUrl);
             if (targetDir) {
                 targetDirs.push(targetDir);
             }
@@ -762,11 +880,79 @@ const checkoutEntities = (handoff, kind, ids) => __awaiter(void 0, void 0, void
     yield registerCheckedOut(handoff, kind, targetDirs);
     logger_1.Logger.success(`${kind[0].toUpperCase()}${kind.slice(1)}s checkout complete — ${checkedOut} ${handoff.dryRun ? 'would be checked out' : 'checked out'}` +
         `${failed.length ? `, ${failed.length} failed` : ''}.`);
-    if (failed.length > 0) {
-        for (const failure of failed) {
-            logger_1.Logger.error(`  - ${failure.id}: ${failure.message}`);
-        }
-        throw new CheckoutError(`${failed.length} ${kind}(s) failed to checkout.`);
+    for (const failure of failed) {
+        logger_1.Logger.error(`  - ${failure.id}: ${failure.message}`);
+    }
+    return failed.length;
+});
+/**
+ * Checkout every published component, pattern, or page of the kind into this workspace. Enumerates
+ * the registry's published ids, then checks each out through the shared client. A per-entity failure
+ * is collected and never aborts the rest; the run throws at the end if any entity failed. Overwrite
+ * prompting is per entity (skipped under `--force`).
+ */
+const checkoutEntities = (handoff, kind, ids) => __awaiter(void 0, void 0, void 0, function* () {
+    const connection = yield (0, exports.resolveConnectionOrThrow)(handoff);
+    const client = (0, client_1.createRegistryClient)({ baseUrl: connection.url, accessToken: connection.accessToken });
+    const published = yield listPublishedIds(kind, client, connection.url);
+    const { selected: targets, unknown } = (0, selection_1.selectIds)(published, ids);
+    if (unknown.length > 0) {
+        throw new CheckoutError(`No ${kind} named ${(0, selection_1.quoteIds)(unknown)} is published in the registry. ` + `Published ${kind}s: ${published.join(', ') || '(none)'}.`);
+    }
+    if (targets.length === 0) {
+        logger_1.Logger.success(`No ${kind}s are published in the registry; nothing to checkout.`);
+        return;
+    }
+    const failed = yield checkoutSelected(handoff, kind, targets, client, connection.url);
+    if (failed > 0) {
+        throw new CheckoutError(`${failed} ${kind}(s) failed to checkout.`);
     }
 });
 exports.checkoutEntities = checkoutEntities;
+/** The entity lanes a catalog run visits, in dependency order: a pattern composes components. */
+const CATALOG_LANES = ['component', 'pattern'];
+/**
+ * Checkout published catalog items into this workspace: every one, or only `ids` when given. An item
+ * was published as a component or as a pattern depending on its declaration, so the lane is looked up
+ * in the registry and the caller never names one.
+ *
+ * A failing lane is reported and never aborts the other. The run throws at the end if any item
+ * failed.
+ */
+const checkoutCatalog = (handoff, ids) => __awaiter(void 0, void 0, void 0, function* () {
+    const connection = yield (0, exports.resolveConnectionOrThrow)(handoff);
+    const client = (0, client_1.createRegistryClient)({ baseUrl: connection.url, accessToken: connection.accessToken });
+    const available = {
+        component: yield listPublishedIds('component', client, connection.url),
+        pattern: yield listPublishedIds('pattern', client, connection.url),
+    };
+    let lanes;
+    if (ids) {
+        const split = (0, selection_1.splitCatalogIds)(ids, available);
+        if (split.ambiguous.length > 0) {
+            throw new CheckoutError(`${(0, selection_1.quoteIds)(split.ambiguous)} is published both as a component and as a pattern. Ask the registry owner to fix the id.`);
+        }
+        if (split.unknown.length > 0) {
+            const publishedIds = [...available.component, ...available.pattern];
+            throw new CheckoutError(`No catalog item named ${(0, selection_1.quoteIds)(split.unknown)} is published in the registry. ` +
+                `Published catalog items: ${publishedIds.join(', ') || '(none)'}.`);
+        }
+        lanes = CATALOG_LANES.map((kind) => ({ kind, targets: split.lanes[kind] }));
+    }
+    else {
+        lanes = CATALOG_LANES.map((kind) => ({ kind, targets: available[kind] }));
+    }
+    const selected = lanes.filter((lane) => lane.targets.length > 0);
+    if (selected.length === 0) {
+        logger_1.Logger.success('No catalog items are published in the registry; nothing to checkout.');
+        return;
+    }
+    let failed = 0;
+    for (const lane of selected) {
+        failed += yield checkoutSelected(handoff, lane.kind, lane.targets, client, connection.url);
+    }
+    if (failed > 0) {
+        throw new CheckoutError(`${failed} catalog item(s) failed to checkout.`);
+    }
+});
+exports.checkoutCatalog = checkoutCatalog;