handoff-app 2.0.0-6 → 2.0.0-8

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 {};

package/dist/catalog/normalize.js

@@ -0,0 +1,115 @@
+"use strict";
+var __rest = (this && this.__rest) || function (s, e) {
+    var t = {};
+    for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)
+        t[p] = s[p];
+    if (s != null && typeof Object.getOwnPropertySymbols === "function")
+        for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) {
+            if (e.indexOf(p[i]) < 0 && Object.prototype.propertyIsEnumerable.call(s, p[i]))
+                t[p[i]] = s[p[i]];
+        }
+    return t;
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeCatalogItem = void 0;
+const lodash_1 = require("lodash");
+const path_1 = __importDefault(require("path"));
+const define_1 = require("./define");
+const implementation_1 = require("./implementation");
+const previews_1 = require("./previews");
+const renderers_1 = require("./renderers");
+/** Imported component values need a file path recovered from the declaration source. */
+const resolveImplementation = (item, options) => {
+    const stamped = item.implementation;
+    const source = { renderer: stamped.renderer, sourceFormat: stamped.format };
+    if (stamped.file) {
+        return Object.assign(Object.assign({}, source), { file: stamped.file });
+    }
+    const declarationDir = path_1.default.dirname(options.declarationPath);
+    const resolved = (0, implementation_1.resolvePropertySource)(options.declarationPath, 'implementation');
+    if (resolved) {
+        if (!(0, implementation_1.isInsideDirectory)(resolved.file, declarationDir)) {
+            options.warn(`Catalog item "${options.fallbackId}" resolves its implementation to "${resolved.file}", outside "${declarationDir}". ` +
+                `Previews still build, but the item cannot be published. Move the file into the item directory to publish it.`);
+        }
+        return Object.assign(Object.assign({}, source), { file: resolved.file, exportName: resolved.exportName });
+    }
+    const sibling = (0, implementation_1.findSiblingComponentFile)(declarationDir, options.declarationPath);
+    if (sibling) {
+        options.warn(`Catalog item "${options.fallbackId}" in "${options.declarationPath}" could not resolve the import behind ` +
+            `"implementation". Using "${path_1.default.basename(sibling)}". Set "implementation" to the file path to be explicit.`);
+        return Object.assign(Object.assign({}, source), { file: sibling });
+    }
+    options.warn(`Catalog item "${options.fallbackId}" in "${options.declarationPath}" could not resolve the import behind ` +
+        `"implementation". Set "implementation" to the file path instead of the imported value.`);
+    return source;
+};
+const quotedList = (values) => values.map((value) => `"${value}"`).join(' or ');
+/** Maps the authoring contract directly into the runtime read model. */
+const normalizeCatalogItem = (moduleExports, options) => {
+    var _a, _b, _c;
+    const item = (_a = moduleExports.default) !== null && _a !== void 0 ? _a : moduleExports;
+    (0, define_1.validateCatalogItem)(item);
+    const { implementation, composition, __args, name, shouldDo, shouldNotDo } = item, meta = __rest(item, ["implementation", "composition", "__args", "name", "shouldDo", "shouldNotDo"]);
+    const id = typeof meta.id === 'string' && meta.id.trim() ? meta.id.trim() : options.fallbackId;
+    const title = name || (0, lodash_1.startCase)(id);
+    const directory = path_1.default.dirname(options.declarationPath);
+    if (composition) {
+        return {
+            kind: 'pattern',
+            item: {
+                id,
+                title,
+                path: directory,
+                description: meta.description,
+                group: meta.group,
+                tags: meta.tags,
+                components: composition.map((ref) => ({
+                    id: ref.ref.trim(),
+                    preview: typeof ref.preview === 'string' ? ref.preview.trim() : undefined,
+                    args: ref.args ? Object.assign({}, ref.args) : undefined,
+                })),
+            },
+        };
+    }
+    const source = resolveImplementation(item, options);
+    const entries = {};
+    for (const [key, value] of Object.entries((_b = meta.entries) !== null && _b !== void 0 ? _b : {})) {
+        if (value)
+            entries[key] = path_1.default.resolve(directory, value);
+    }
+    const entryKey = (0, renderers_1.entryKeyFor)(source.renderer, source.sourceFormat);
+    if (!source.file) {
+        throw new Error(`Catalog item "${id}" needs an implementation file. Set implementation to a file path.`);
+    }
+    entries[entryKey] = path_1.default.resolve(directory, source.file);
+    // Existing builders consume template as the primary build input for every renderer.
+    entries.template = entries[entryKey];
+    // A wrong renderer builds a broken preview without failing on its own, so a mismatch is fatal.
+    // `config/runtime.ts` turns the throw into a skipped item that retries on the next save.
+    const claim = (0, renderers_1.sourceForFile)(source.file);
+    if (claim && !claim.renderers.includes(source.renderer)) {
+        throw new Error(`Catalog item "${id}" declares renderer "${source.renderer}", but "${source.file}" is a ${quotedList(claim.renderers)} source. ` +
+            `Declare it from ${quotedList(claim.renderers.map(renderers_1.moduleFor))}.`);
+    }
+    // Only a suffix that names a format is conclusive. A `.stories.tsx` file is always CSF, while a
+    // plain `.tsx` file says nothing about its format.
+    const fileFormat = claim === null || claim === void 0 ? void 0 : claim.format;
+    // The comparison narrows a single-format union to `never`, so read the helper first.
+    const fileFormatHelper = fileFormat && renderers_1.SOURCE_FORMATS[fileFormat].helper;
+    if (fileFormat && fileFormat !== source.sourceFormat) {
+        throw new Error(`Catalog item "${id}" declares "${source.file}" as a plain source, but it is a "${fileFormat}" source. ` +
+            `Wrap it with ${fileFormatHelper}() from "${(0, renderers_1.moduleFor)(source.renderer)}".`);
+    }
+    if (((_c = meta.page) === null || _c === void 0 ? void 0 : _c.slices) && !Array.isArray(meta.page.slices)) {
+        throw new Error(`Catalog item "${id}" has invalid page.slices; expected an array.`);
+    }
+    return {
+        kind: 'component',
+        item: Object.assign(Object.assign(Object.assign(Object.assign({}, meta), { id, title: name || '', path: directory, should_do: shouldDo, should_not_do: shouldNotDo, renderer: source.renderer, sourceFormat: source.sourceFormat, entries }), (source.exportName && source.exportName !== 'default' ? { componentExport: source.exportName } : {})), { previews: (0, previews_1.createCatalogPreviews)(moduleExports, options.declarationPath) }),
+    };
+};
+exports.normalizeCatalogItem = normalizeCatalogItem;

package/dist/catalog/previews.d.ts

@@ -0,0 +1,18 @@
+import type { OptionalPreviewRender } from '../transformers/preview/types';
+/**
+ * Exported names in the order the source declares them.
+ *
+ * The evaluated module cannot supply this order. esbuild emits its export map alphabetically, and
+ * an ESM namespace object has sorted keys by specification.
+ */
+export declare const readExportOrderFromSource: (sourceCode: string) => string[];
+/** Exported names in source order, or an empty list when the file cannot be read. */
+export declare const readExportOrder: (filePath: string) => string[];
+/**
+ * Re-keys previews into the given order. A preview the order does not mention is placed after the
+ * ordered ones, so an export form the parser does not recognize falls back to the evaluated order
+ * rather than dropping the preview.
+ */
+export declare const orderPreviews: <T>(previews: Record<string, T>, order: string[]) => Record<string, T>;
+/** Collects the named exports of a declaration module as previews, in declaration order. */
+export declare const createCatalogPreviews: (moduleExports: Record<string, unknown>, declarationPath?: string) => Record<string, OptionalPreviewRender>;

package/dist/catalog/previews.js

@@ -0,0 +1,106 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createCatalogPreviews = exports.orderPreviews = exports.readExportOrder = exports.readExportOrderFromSource = void 0;
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const lodash_1 = require("lodash");
+/**
+ * A declaration module exports more than previews: the item itself, the implementation it
+ * re-exports, helper values. Accept only a plain object that owns `args` or `name`, so an exported
+ * component or helper is never mistaken for a preview.
+ *
+ * `getCsfStoryEntries` does not fit here: on a CSF file every named export is a story, and on a
+ * declaration file it is not.
+ */
+const isPreviewDeclaration = (value) => {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    return Object.prototype.hasOwnProperty.call(value, 'args') || Object.prototype.hasOwnProperty.call(value, 'name');
+};
+/** Matches an exported binding, an export list, or a CommonJS export assignment. */
+const EXPORT_PATTERNS = [
+    { pattern: /\bexport\s+(?:async\s+)?(?:const|let|var|function\s*\*?|class)\s+([A-Za-z_$][\w$]*)/g },
+    { pattern: /\bexport\s*(?!type[\s{])\{([^}]*)\}/g, list: true },
+    { pattern: /\bexports\.([A-Za-z_$][\w$]*)\s*=/g },
+];
+/** Reads the exported name an export-list specifier binds: `A as B` exports `B`, `A` exports `A`. */
+const readExportedName = (specifier) => {
+    const name = specifier.trim().replace(/^type\s+/, '');
+    if (!name)
+        return undefined;
+    const aliased = name.match(/^[A-Za-z_$][\w$]*\s+as\s+([A-Za-z_$][\w$]*)$/);
+    if (aliased)
+        return aliased[1];
+    return /^[A-Za-z_$][\w$]*$/.test(name) ? name : undefined;
+};
+/**
+ * Exported names in the order the source declares them.
+ *
+ * The evaluated module cannot supply this order. esbuild emits its export map alphabetically, and
+ * an ESM namespace object has sorted keys by specification.
+ */
+const readExportOrderFromSource = (sourceCode) => {
+    const found = [];
+    for (const { pattern, list } of EXPORT_PATTERNS) {
+        for (const match of sourceCode.matchAll(pattern)) {
+            const names = list ? match[1].split(',').map(readExportedName) : [match[1]];
+            names.forEach((name, offset) => {
+                if (name)
+                    found.push({ index: match.index + offset, name });
+            });
+        }
+    }
+    const order = [];
+    const seen = new Set();
+    for (const { name } of found.sort((a, b) => a.index - b.index)) {
+        if (seen.has(name))
+            continue;
+        seen.add(name);
+        order.push(name);
+    }
+    return order;
+};
+exports.readExportOrderFromSource = readExportOrderFromSource;
+/** Exported names in source order, or an empty list when the file cannot be read. */
+const readExportOrder = (filePath) => {
+    try {
+        return (0, exports.readExportOrderFromSource)(fs_extra_1.default.readFileSync(filePath, 'utf8'));
+    }
+    catch (_a) {
+        return [];
+    }
+};
+exports.readExportOrder = readExportOrder;
+/**
+ * Re-keys previews into the given order. A preview the order does not mention is placed after the
+ * ordered ones, so an export form the parser does not recognize falls back to the evaluated order
+ * rather than dropping the preview.
+ */
+const orderPreviews = (previews, order) => {
+    if (order.length === 0)
+        return previews;
+    const ranked = new Set(order.filter((name) => name in previews));
+    const rest = Object.keys(previews).filter((name) => !ranked.has(name));
+    return Object.fromEntries([...ranked, ...rest].map((name) => [name, previews[name]]));
+};
+exports.orderPreviews = orderPreviews;
+/** Collects the named exports of a declaration module as previews, in declaration order. */
+const createCatalogPreviews = (moduleExports, declarationPath) => {
+    var _a, _b;
+    const previews = {};
+    for (const [exportName, value] of Object.entries(moduleExports !== null && moduleExports !== void 0 ? moduleExports : {})) {
+        if (exportName === 'default' || exportName === '__esModule')
+            continue;
+        if (!isPreviewDeclaration(value))
+            continue;
+        if (value && typeof value === 'object' && ('values' in value || 'title' in value)) {
+            throw new Error(`Preview "${exportName}" uses removed fields. Use args and name. See UPGRADE.md#catalog-items.`);
+        }
+        const preview = value;
+        previews[exportName] = Object.assign({ title: preview.name || (0, lodash_1.startCase)(exportName), values: Object.assign({}, ((_a = preview.args) !== null && _a !== void 0 ? _a : {})), url: (_b = preview.url) !== null && _b !== void 0 ? _b : '' }, (preview.usage ? { usage: preview.usage } : {}));
+    }
+    return declarationPath ? (0, exports.orderPreviews)(previews, (0, exports.readExportOrder)(declarationPath)) : previews;
+};
+exports.createCatalogPreviews = createCatalogPreviews;

package/dist/catalog/renderers.d.ts

@@ -0,0 +1,43 @@
+/**
+ * This module has no runtime imports, so every layer can use the renderer registry.
+ * Import it directly to avoid the catalog barrel dependencies, including `fs-extra`.
+ */
+/** Add a renderer only with its preview support. */
+export type RendererKind = 'react' | 'handlebars';
+/** How an implementation file is written, independent of the renderer that renders it. */
+export type SourceFormat = 'csf';
+/** Key in `entries` that holds an implementation file. */
+export type EntryKey = 'component' | 'template' | 'story';
+export type ComponentSource = {
+    renderer: RendererKind;
+    sourceFormat?: SourceFormat;
+};
+type RendererDefinition = {
+    /** Declaration module that supplies this renderer. */
+    module: string;
+    /** Entry key normalization writes the implementation file to. */
+    entryKey: EntryKey;
+};
+type SourceFormatDefinition = {
+    /** Renderers this format applies to. */
+    renderers: RendererKind[];
+    entryKey: EntryKey;
+    /** Export of the renderer module that declares an implementation in this format. */
+    helper: string;
+};
+export declare const RENDERERS: Record<RendererKind, RendererDefinition>;
+export declare const SOURCE_FORMATS: Record<SourceFormat, SourceFormatDefinition>;
+/** Which renderers can own a file name, and the source format the name implies. */
+export type SourceClaim = {
+    renderers: RendererKind[];
+    format?: SourceFormat;
+};
+export declare const isRendererKind: (value: unknown) => value is RendererKind;
+export declare const isSourceFormat: (value: unknown) => value is SourceFormat;
+/** What the file name says about a source, matched case-insensitively. Undefined when no suffix claims it. */
+export declare const sourceForFile: (file: string | undefined) => SourceClaim | undefined;
+/** Entry key normalization records the implementation file under, if the renderer is registered. */
+export declare const entryKeyFor: (renderer: RendererKind | undefined, sourceFormat?: SourceFormat) => EntryKey | undefined;
+/** Declaration module that supplies a renderer, or undefined when it has no module of its own. */
+export declare const moduleFor: (renderer: RendererKind | undefined) => string | undefined;
+export {};

package/dist/catalog/renderers.js

@@ -0,0 +1,62 @@
+"use strict";
+/**
+ * This module has no runtime imports, so every layer can use the renderer registry.
+ * Import it directly to avoid the catalog barrel dependencies, including `fs-extra`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.moduleFor = exports.entryKeyFor = exports.sourceForFile = exports.isSourceFormat = exports.isRendererKind = exports.SOURCE_FORMATS = exports.RENDERERS = void 0;
+exports.RENDERERS = {
+    react: {
+        module: 'handoff-app/react',
+        entryKey: 'component',
+    },
+    handlebars: {
+        module: 'handoff-app/handlebars',
+        entryKey: 'template',
+    },
+};
+exports.SOURCE_FORMATS = {
+    csf: {
+        renderers: ['react'],
+        entryKey: 'story',
+        helper: 'fromCSF',
+    },
+};
+/**
+ * This table never decides a renderer. The declaration states it, and the table only checks the
+ * implementation file against it. Keying by suffix keeps one row per file name: a suffix that more
+ * than one renderer owns lists them all, and a duplicate key is a compile error. A file that no
+ * row claims is not checked.
+ */
+const SOURCE_SUFFIXES = {
+    '.stories.tsx': { renderers: ['react'], format: 'csf' },
+    '.stories.jsx': { renderers: ['react'], format: 'csf' },
+    '.stories.ts': { renderers: ['react'], format: 'csf' },
+    '.stories.js': { renderers: ['react'], format: 'csf' },
+    '.tsx': { renderers: ['react'] },
+    '.jsx': { renderers: ['react'] },
+    '.hbs': { renderers: ['handlebars'] },
+};
+/** Longest first, so `.stories.tsx` reads as a CSF source rather than a plain React source. */
+const SUFFIXES_BY_LENGTH = Object.keys(SOURCE_SUFFIXES).sort((first, second) => second.length - first.length);
+const RENDERER_KINDS = Object.keys(exports.RENDERERS);
+const SOURCE_FORMAT_KINDS = Object.keys(exports.SOURCE_FORMATS);
+const isRendererKind = (value) => RENDERER_KINDS.includes(value);
+exports.isRendererKind = isRendererKind;
+const isSourceFormat = (value) => SOURCE_FORMAT_KINDS.includes(value);
+exports.isSourceFormat = isSourceFormat;
+/** What the file name says about a source, matched case-insensitively. Undefined when no suffix claims it. */
+const sourceForFile = (file) => {
+    if (!file)
+        return undefined;
+    const lowerCased = file.toLowerCase();
+    const suffix = SUFFIXES_BY_LENGTH.find((candidate) => lowerCased.endsWith(candidate));
+    return suffix ? SOURCE_SUFFIXES[suffix] : undefined;
+};
+exports.sourceForFile = sourceForFile;
+/** Entry key normalization records the implementation file under, if the renderer is registered. */
+const entryKeyFor = (renderer, sourceFormat) => { var _a, _b; return sourceFormat ? (_a = exports.SOURCE_FORMATS[sourceFormat]) === null || _a === void 0 ? void 0 : _a.entryKey : renderer ? (_b = exports.RENDERERS[renderer]) === null || _b === void 0 ? void 0 : _b.entryKey : undefined; };
+exports.entryKeyFor = entryKeyFor;
+/** Declaration module that supplies a renderer, or undefined when it has no module of its own. */
+const moduleFor = (renderer) => { var _a; return (renderer ? (_a = exports.RENDERERS[renderer]) === null || _a === void 0 ? void 0 : _a.module : undefined); };
+exports.moduleFor = moduleFor;

package/dist/catalog/types.d.ts

@@ -0,0 +1,63 @@
+import type { RendererKind, SourceFormat } from './renderers';
+import type { ComponentObject } from '../transformers/preview/types';
+/**
+ * How an implementation file is written. `fromCSF('./Button.stories.tsx')` is shorthand for
+ * `{ format: 'csf', file: './Button.stories.tsx' }`.
+ */
+export type SourceDescriptor<TFormat extends string = string> = {
+    format: TFormat;
+    file: string;
+};
+export type CsfSource = SourceDescriptor<'csf'>;
+/** The loader recovers the file for an imported component in `value` from the declaration source. */
+export type NormalizedImplementation = {
+    renderer: RendererKind;
+    format?: SourceFormat;
+    file?: string;
+    value?: unknown;
+};
+export type CatalogItemEntries = Pick<NonNullable<ComponentObject['entries']>, 'js' | 'scss' | 'schema' | 'templates'>;
+/**
+ * Metadata a catalog item can carry. `type` and `categories` are free-form classification, so a
+ * term such as atom, element, or block goes there.
+ */
+export type CatalogItemMeta = Partial<Omit<ComponentObject, 'previews' | 'previewOrder' | 'entries' | 'title' | 'should_do' | 'should_not_do' | 'renderer' | 'sourceFormat' | 'componentExport'>> & {
+    id?: string;
+    name?: string;
+    description?: string;
+    group?: string;
+    entries?: CatalogItemEntries;
+    shouldDo?: string[];
+    shouldNotDo?: string[];
+};
+/** One member of a composition. `ref` is the id of another catalog item. */
+export type CompositionRef = {
+    ref: string;
+    preview?: string;
+    args?: Record<string, unknown>;
+};
+/** A named preview, exported next to the catalog item it belongs to. */
+export type CatalogPreview<TArgs = Record<string, unknown>> = {
+    /** Display title. Defaults to a start-cased form of the export name. */
+    name?: string;
+    args?: TArgs;
+    usage?: string;
+    url?: string;
+};
+/**
+ * `__args` exists only in the type system so `Preview<typeof item>` can infer the preview argument type.
+ */
+export type CatalogItem<TArgs = Record<string, unknown>> = CatalogItemMeta & {
+    implementation?: unknown;
+    composition?: CompositionRef[];
+    readonly __args?: TArgs;
+};
+/** Preview type for a catalog item, with its argument type applied. */
+export type Preview<TItem> = TItem extends {
+    readonly __args?: infer TArgs;
+} ? CatalogPreview<Partial<NonNullable<TArgs>>> : never;
+/** Input accepted by every `defineCatalogItem` entry point. */
+export type CatalogItemInput = CatalogItemMeta & {
+    implementation?: unknown;
+    composition?: CompositionRef[];
+};

package/dist/cli/auth/device.d.ts

@@ -1,8 +1,13 @@
 import { type CliAuth } from './store';
 export interface LoginOptions {
     openBrowser?: boolean;
+    /** Profile the issued credential is saved under. Omitted, it is the default profile. */
+    profile?: string;
 }
-/** Complete the device grant and persist the one-time plaintext access token for this workspace. */
+/**
+ * Complete the device grant and persist the one-time plaintext access token for this workspace,
+ * under the selected profile.
+ */
 export declare const loginWithDevice: (workingPath: string, remoteUrl: string, options?: LoginOptions) => Promise<CliAuth>;
 /**
  * Best-effort remote revocation. The caller must clear the local credential regardless of failure.

package/dist/cli/auth/device.js

@@ -53,7 +53,10 @@ const shouldOpenBrowser = (options) => {
     return process.env.HANDOFF_LOGIN_NO_BROWSER !== '1' && process.env.HANDOFF_LOGIN_NO_BROWSER !== 'true';
 };
 const positiveNumberOr = (value, fallback) => typeof value === 'number' && Number.isFinite(value) && value > 0 ? value : fallback;
-/** Complete the device grant and persist the one-time plaintext access token for this workspace. */
+/**
+ * Complete the device grant and persist the one-time plaintext access token for this workspace,
+ * under the selected profile.
+ */
 const loginWithDevice = (workingPath_1, remoteUrl_1, ...args_1) => __awaiter(void 0, [workingPath_1, remoteUrl_1, ...args_1], void 0, function* (workingPath, remoteUrl, options = {}) {
     const baseUrl = (0, store_1.normalizeRegistryUrl)(remoteUrl);
     let deviceResponse;
@@ -115,7 +118,7 @@ const loginWithDevice = (workingPath_1, remoteUrl_1, ...args_1) => __awaiter(voi
                 accessToken: token.access_token,
                 expiresAtMs: Date.now() + expiresIn * 1000,
             };
-            yield (0, store_1.writeCliAuth)(workingPath, auth);
+            yield (0, store_1.writeCliAuth)(workingPath, auth, options.profile);
             return auth;
         }
         const failure = responseError(token);