handoff-app 2.0.0-5 → 2.0.0-7

package/dist/registry/db/schema.d.ts

@@ -193,6 +193,23 @@ export declare const components: import("drizzle-orm/pg-core").PgTableWithColumn
             identity: undefined;
             generated: undefined;
         }, {}, {}>;
+        sourceFormat: import("drizzle-orm/pg-core").PgColumn<{
+            name: "source_format";
+            tableName: "components";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
         tags: import("drizzle-orm/pg-core").PgColumn<{
             name: "tags";
             tableName: "components";
@@ -3533,6 +3550,23 @@ export declare const registrySchema: {
                 identity: undefined;
                 generated: undefined;
             }, {}, {}>;
+            sourceFormat: import("drizzle-orm/pg-core").PgColumn<{
+                name: "source_format";
+                tableName: "components";
+                dataType: "string";
+                columnType: "PgText";
+                data: string;
+                driverParam: string;
+                notNull: false;
+                hasDefault: false;
+                isPrimaryKey: false;
+                isAutoincrement: false;
+                hasRuntimeDefault: false;
+                enumValues: [string, ...string[]];
+                baseColumn: never;
+                identity: undefined;
+                generated: undefined;
+            }, {}, {}>;
             tags: import("drizzle-orm/pg-core").PgColumn<{
                 name: "tags";
                 tableName: "components";

package/dist/registry/db/schema.js

@@ -51,6 +51,8 @@ exports.components = (0, pg_core_1.pgTable)('components', {
     group: (0, pg_core_1.text)('group'),
     type: (0, pg_core_1.text)('type'),
     renderer: (0, pg_core_1.text)('renderer'),
+    /** How the implementation file is written (`csf`), when the renderer alone does not say. */
+    sourceFormat: (0, pg_core_1.text)('source_format'),
     tags: (0, pg_core_1.jsonb)('tags').$type(),
     categories: (0, pg_core_1.jsonb)('categories').$type(),
     /** Full normalized component record. */

package/dist/registry/publish/index.d.ts

@@ -1,8 +1,9 @@
 /**
  * Connected-workspace publish orchestration.
  *
- * `publish <components|patterns|pages> <id>` prepares one entity and uploads its record, source files,
- * applicable rendered artifacts, and build metadata through the shared registry client.
+ * `publish <catalog|pages> <id>` prepares one entity and uploads its record, source files, applicable
+ * rendered artifacts, and build metadata through the shared registry client. A catalog item's lane
+ * comes from its declaration, so the caller names items and this module resolves the lane.
  *
  * The build is targeted: a component builds the global artifacts + that component; a pattern builds
  * the global artifacts + the components it composes + the pattern itself. This is the smallest build
@@ -56,3 +57,13 @@ export declare const publishEntity: (handoff: Handoff, kind: TransferEntityKind,
  * run throws at the end if any entity failed.
  */
 export declare const publishEntities: (handoff: Handoff, kind: TransferEntityKind, ids?: string[]) => Promise<void>;
+/**
+ * Publish the catalog items declared in this connected workspace: every one, or only `ids` when
+ * given. An item takes the component lane or the pattern lane depending on whether it declares an
+ * implementation or a composition, so the caller names items and never names a lane.
+ *
+ * One build covers both lanes, because building the patterns already builds every component they
+ * compose. A failing lane is reported and never aborts the other. The run throws at the end if any
+ * item failed.
+ */
+export declare const publishCatalog: (handoff: Handoff, ids?: string[]) => Promise<void>;

package/dist/registry/publish/index.js

@@ -2,8 +2,9 @@
 /**
  * Connected-workspace publish orchestration.
  *
- * `publish <components|patterns|pages> <id>` prepares one entity and uploads its record, source files,
- * applicable rendered artifacts, and build metadata through the shared registry client.
+ * `publish <catalog|pages> <id>` prepares one entity and uploads its record, source files, applicable
+ * rendered artifacts, and build metadata through the shared registry client. A catalog item's lane
+ * comes from its declaration, so the caller names items and this module resolves the lane.
  *
  * The build is targeted: a component builds the global artifacts + that component; a pattern builds
  * the global artifacts + the components it composes + the pattern itself. This is the smallest build
@@ -22,7 +23,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.publishEntities = exports.publishEntity = exports.publishedLabel = exports.resolveTransport = exports.resolveConnectionOrThrow = exports.assertPublishableWorkspace = exports.PublishError = void 0;
+exports.publishCatalog = exports.publishEntities = exports.publishEntity = exports.publishedLabel = exports.resolveTransport = exports.resolveConnectionOrThrow = exports.assertPublishableWorkspace = exports.PublishError = void 0;
 const css_1 = require("../../transformers/preview/component/css");
 const javascript_1 = require("../../transformers/preview/component/javascript");
 const builder_1 = __importDefault(require("../../transformers/preview/component/builder"));
@@ -55,6 +56,22 @@ const assertPublishableWorkspace = (handoff) => {
     }
 };
 exports.assertPublishableWorkspace = assertPublishableWorkspace;
+/** The entity lanes a catalog run visits, in dependency order: a pattern composes components. */
+const CATALOG_LANES = ['component', 'pattern'];
+const isCatalogLane = (kind) => CATALOG_LANES.some((lane) => lane === kind);
+/**
+ * Refuse a catalog run while the workspace declares one id twice. Discovery keeps the first
+ * declaration and skips the rest, so a publish uploads a catalog that silently omits an item.
+ */
+const assertUniqueCatalogIds = (handoff) => {
+    var _a, _b;
+    const duplicates = (_b = (_a = handoff.runtimeConfig) === null || _a === void 0 ? void 0 : _a.duplicateCatalogIds) !== null && _b !== void 0 ? _b : [];
+    if (duplicates.length === 0)
+        return;
+    throw new PublishError(`Catalog id${duplicates.length > 1 ? 's' : ''} declared twice: ` +
+        duplicates.map(({ id, kept, skipped }) => `"${id}" (${kept} and ${skipped})`).join('; ') +
+        '. Give each catalog item a unique id.');
+};
 /**
  * Ensure the workspace is a connected workspace able to publish: workspace runtime mode (registry
  * hosts do not publish) and a resolved registry URL + access token. Throws an actionable
@@ -95,11 +112,11 @@ const publishedLabel = (handoff) => (handoff.dryRun ? 'Would publish' : 'Publish
 exports.publishedLabel = publishedLabel;
 /** Run the smallest build that guarantees the selected entity's artifacts are current. */
 const runTargetedBuild = (handoff, kind, id) => __awaiter(void 0, void 0, void 0, function* () {
-    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m;
+    var _a, _b, _c, _d;
     // Pages carry no rendered artifacts (raw markdown is rendered at runtime), so there is nothing to
     // build — the package is assembled directly from the discovered page record + its `.md`.
     if (kind === 'page') {
-        if (!((_c = (_b = (_a = handoff.runtimeConfig) === null || _a === void 0 ? void 0 : _a.entries) === null || _b === void 0 ? void 0 : _b.pages) === null || _c === void 0 ? void 0 : _c[id])) {
+        if (!((_a = handoff.runtimeConfig) === null || _a === void 0 ? void 0 : _a.entities.pages[id])) {
             throw new package_1.PublishPackageError(`Page "${id}" is not declared in this workspace.`);
         }
         return;
@@ -109,13 +126,13 @@ const runTargetedBuild = (handoff, kind, id) => __awaiter(void 0, void 0, void 0
     yield (0, javascript_1.buildMainJS)(handoff);
     yield (0, css_1.buildMainCss)(handoff);
     if (kind === 'component') {
-        if (!((_f = (_e = (_d = handoff.runtimeConfig) === null || _d === void 0 ? void 0 : _d.entries) === null || _e === void 0 ? void 0 : _e.components) === null || _f === void 0 ? void 0 : _f[id])) {
+        if (!((_b = handoff.runtimeConfig) === null || _b === void 0 ? void 0 : _b.entities.components[id])) {
             throw new package_1.PublishPackageError(`Component "${id}" is not declared in this workspace.`);
         }
         yield (0, builder_1.default)(handoff, id);
         return;
     }
-    const pattern = (_j = (_h = (_g = handoff.runtimeConfig) === null || _g === void 0 ? void 0 : _g.entries) === null || _h === void 0 ? void 0 : _h.patterns) === null || _j === void 0 ? void 0 : _j[id];
+    const pattern = (_c = handoff.runtimeConfig) === null || _c === void 0 ? void 0 : _c.entities.patterns[id];
     if (!pattern) {
         throw new package_1.PublishPackageError(`Pattern "${id}" is not declared in this workspace.`);
     }
@@ -123,7 +140,7 @@ const runTargetedBuild = (handoff, kind, id) => __awaiter(void 0, void 0, void 0
     // then compose just this pattern.
     const referencedComponentIds = new Set(pattern.components.map((ref) => ref.id));
     for (const componentId of Array.from(referencedComponentIds)) {
-        if ((_m = (_l = (_k = handoff.runtimeConfig) === null || _k === void 0 ? void 0 : _k.entries) === null || _l === void 0 ? void 0 : _l.components) === null || _m === void 0 ? void 0 : _m[componentId]) {
+        if ((_d = handoff.runtimeConfig) === null || _d === void 0 ? void 0 : _d.entities.components[componentId]) {
             yield (0, builder_1.default)(handoff, componentId);
         }
     }
@@ -134,6 +151,8 @@ const runTargetedBuild = (handoff, kind, id) => __awaiter(void 0, void 0, void 0
  * receive a targeted build, while pages are packaged directly from their source.
  */
 const publishEntity = (handoff, kind, id) => __awaiter(void 0, void 0, void 0, function* () {
+    if (isCatalogLane(kind))
+        assertUniqueCatalogIds(handoff);
     const { client, url } = yield (0, exports.resolveTransport)(handoff);
     if (!handoff.skipBuild) {
         logger_1.Logger.info(kind === 'page' ? `Preparing page "${id}" for publish…` : `Building ${kind} "${id}" for publish…`);
@@ -200,22 +219,18 @@ const selectEntityIds = (available, requested, kind) => {
     return selected;
 };
 /**
- * Publish the components, patterns or pages declared in this connected workspace: every one of the
- * kind, or only `ids` when given. Builds the kind once, assembles each entity's package, skips
- * entities whose content hash already matches the registry (unless `--force`), and reports
- * published/unchanged/failed counts. A per-entity failure is collected and never aborts the rest; the
- * run throws at the end if any entity failed.
+ * Assemble and upload the selected entities of one kind. The caller runs the build, because a catalog
+ * run covers both entity lanes from one build.
+ *
+ * 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 publishEntities = (handoff, kind, ids) => __awaiter(void 0, void 0, void 0, function* () {
-    const { client, url } = yield (0, exports.resolveTransport)(handoff);
-    if (!handoff.skipBuild) {
-        logger_1.Logger.info(`Building ${kind}s for publish…`);
-        yield runBulkBuild(handoff, kind);
-    }
+const uploadEntities = (handoff, transport, kind, ids) => __awaiter(void 0, void 0, void 0, function* () {
+    const { client, url } = transport;
     const targets = selectEntityIds(yield listWorkspaceEntityIds(handoff, kind), ids, kind);
     if (targets.length === 0) {
         logger_1.Logger.success(`No ${kind}s are declared in this workspace; nothing to publish.`);
-        return;
+        return 0;
     }
     // Without a registry there is nothing to compare against, so a dry run reports every target.
     let remote = [];
@@ -255,11 +270,80 @@ const publishEntities = (handoff, kind, ids) => __awaiter(void 0, void 0, void 0
     }
     logger_1.Logger.success(`${kind[0].toUpperCase()}${kind.slice(1)}s publish complete — ${published} ${handoff.dryRun ? 'would be published' : 'published'}, ` +
         `${unchanged} unchanged${failed.length ? `, ${failed.length} failed` : ''}.`);
-    if (failed.length > 0) {
-        for (const failure of failed) {
-            logger_1.Logger.error(`  - ${failure.id}: ${failure.message}`);
-        }
-        throw new PublishError(`${failed.length} ${kind}(s) failed to publish.`);
+    for (const failure of failed) {
+        logger_1.Logger.error(`  - ${failure.id}: ${failure.message}`);
+    }
+    return failed.length;
+});
+/**
+ * Publish the components, patterns or pages declared in this connected workspace: every one of the
+ * kind, or only `ids` when given. Builds the kind once, assembles each entity's package, skips
+ * entities whose content hash already matches the registry (unless `--force`), and reports
+ * published/unchanged/failed counts. A per-entity failure is collected and never aborts the rest; the
+ * run throws at the end if any entity failed.
+ */
+const publishEntities = (handoff, kind, ids) => __awaiter(void 0, void 0, void 0, function* () {
+    if (isCatalogLane(kind))
+        assertUniqueCatalogIds(handoff);
+    const transport = yield (0, exports.resolveTransport)(handoff);
+    if (!handoff.skipBuild) {
+        logger_1.Logger.info(`Building ${kind}s for publish…`);
+        yield runBulkBuild(handoff, kind);
+    }
+    const failed = yield uploadEntities(handoff, transport, kind, ids);
+    if (failed > 0) {
+        throw new PublishError(`${failed} ${kind}(s) failed to publish.`);
     }
 });
 exports.publishEntities = publishEntities;
+/**
+ * Resolve which lane each requested catalog id belongs to. Without ids every lane runs in full. An
+ * unknown id is reported against the whole catalog, because the caller never chose a lane to report
+ * it against.
+ */
+const resolveCatalogLanes = (handoff, ids) => __awaiter(void 0, void 0, void 0, function* () {
+    if (!ids) {
+        return CATALOG_LANES.map((kind) => ({ kind }));
+    }
+    const available = {
+        component: yield listWorkspaceEntityIds(handoff, 'component'),
+        pattern: yield listWorkspaceEntityIds(handoff, 'pattern'),
+    };
+    const { lanes, unknown, ambiguous } = (0, selection_1.splitCatalogIds)(ids, available);
+    if (ambiguous.length > 0) {
+        throw new PublishError(`${(0, selection_1.quoteIds)(ambiguous)} names both a component and a pattern in this workspace. Give each catalog item a unique id.`);
+    }
+    if (unknown.length > 0) {
+        const declared = [...available.component, ...available.pattern];
+        throw new PublishError(`No catalog item named ${(0, selection_1.quoteIds)(unknown)} is declared in this workspace. ` +
+            `Declared catalog items: ${declared.join(', ') || '(none)'}.`);
+    }
+    return CATALOG_LANES.map((kind) => ({ kind, ids: lanes[kind] })).filter((lane) => lane.ids.length > 0);
+});
+/**
+ * Publish the catalog items declared in this connected workspace: every one, or only `ids` when
+ * given. An item takes the component lane or the pattern lane depending on whether it declares an
+ * implementation or a composition, so the caller names items and never names a lane.
+ *
+ * One build covers both lanes, because building the patterns already builds every component they
+ * compose. A failing lane is reported and never aborts the other. The run throws at the end if any
+ * item failed.
+ */
+const publishCatalog = (handoff, ids) => __awaiter(void 0, void 0, void 0, function* () {
+    assertUniqueCatalogIds(handoff);
+    const transport = yield (0, exports.resolveTransport)(handoff);
+    const lanes = yield resolveCatalogLanes(handoff, ids);
+    if (!handoff.skipBuild) {
+        logger_1.Logger.info('Building catalog items for publish…');
+        // The pattern build runs the component build first, so one call covers both lanes.
+        yield runBulkBuild(handoff, 'pattern');
+    }
+    let failed = 0;
+    for (const lane of lanes) {
+        failed += yield uploadEntities(handoff, transport, lane.kind, lane.ids);
+    }
+    if (failed > 0) {
+        throw new PublishError(`${failed} catalog item(s) failed to publish.`);
+    }
+});
+exports.publishCatalog = publishCatalog;

package/dist/registry/publish/package.js

@@ -52,12 +52,14 @@ class PublishPackageError extends Error {
 }
 exports.PublishPackageError = PublishPackageError;
 /**
- * Build a registry-safe `item` record: the built summary enriched with the renderer and the entry
+ * Build a registry-safe `item` record: the built summary enriched with the renderer, its source
+ * format, and the entry
  * source-file paths **remapped** from absolute workspace locations to the registry-safe relative
  * paths the uploaded source files use. Workspace-absolute paths never cross to the registry, and a
  * later checkout can reconstruct the entity from the relative entries + uploaded files.
  */
 const enrichItem = (handoff, kind, id, summary) => __awaiter(void 0, void 0, void 0, function* () {
+    var _a;
     const runtime = kind === 'component' ? yield handoff.store.components.get(id) : yield handoff.store.patterns.get(id);
     if (!runtime) {
         return summary;
@@ -69,6 +71,17 @@ const enrichItem = (handoff, kind, id, summary) => __awaiter(void 0, void 0, voi
     if (renderer) {
         item.renderer = renderer;
     }
+    const sourceFormat = runtime.sourceFormat;
+    if (sourceFormat) {
+        item.sourceFormat = sourceFormat;
+    }
+    const componentExport = runtime.componentExport;
+    if (componentExport)
+        item.componentExport = componentExport;
+    if (kind === 'component') {
+        // PostgreSQL jsonb does not preserve object key order.
+        item.previewOrder = Object.keys((_a = runtime.previews) !== null && _a !== void 0 ? _a : {});
+    }
     if (rawEntries && sourceDir) {
         const remapped = {};
         for (const [key, value] of Object.entries(rawEntries)) {

package/dist/registry/selection.d.ts

@@ -4,9 +4,29 @@
  * Every bulk operation discovers what is available (declared locally or published remotely) and may
  * be asked for only part of it. Splitting the request into what exists and what does not lets each
  * caller build its own actionable error while the matching lives in one place.
+ *
+ * A catalog request needs one more step. A catalog item normalizes into a component or a pattern
+ * from its declaration, so the CLI names the item and the lane is looked up here.
  */
 /** Narrow an available list to the requested subset, separating out ids that do not exist. */
 export declare const selectIds: (available: string[], requested?: string[]) => {
     selected: string[];
     unknown: string[];
 };
+/** Catalog item ids grouped by lane. */
+export interface CatalogLanes {
+    component: string[];
+    pattern: string[];
+}
+/**
+ * Route each requested catalog id to its lane. The two lanes are keyed separately, so nothing stops a
+ * workspace from declaring one id twice. Such an id is reported rather than guessed, because picking
+ * a lane silently would act on the wrong entity.
+ */
+export declare const splitCatalogIds: (requested: string[], available: CatalogLanes) => {
+    lanes: CatalogLanes;
+    unknown: string[];
+    ambiguous: string[];
+};
+/** Quote ids for an error message: `"button", "card"`. */
+export declare const quoteIds: (ids: string[]) => string;

package/dist/registry/selection.js

@@ -5,9 +5,12 @@
  * Every bulk operation discovers what is available (declared locally or published remotely) and may
  * be asked for only part of it. Splitting the request into what exists and what does not lets each
  * caller build its own actionable error while the matching lives in one place.
+ *
+ * A catalog request needs one more step. A catalog item normalizes into a component or a pattern
+ * from its declaration, so the CLI names the item and the lane is looked up here.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.selectIds = void 0;
+exports.quoteIds = exports.splitCatalogIds = exports.selectIds = void 0;
 /** Narrow an available list to the requested subset, separating out ids that do not exist. */
 const selectIds = (available, requested) => {
     if (!requested) {
@@ -20,3 +23,36 @@ const selectIds = (available, requested) => {
     };
 };
 exports.selectIds = selectIds;
+/**
+ * Route each requested catalog id to its lane. The two lanes are keyed separately, so nothing stops a
+ * workspace from declaring one id twice. Such an id is reported rather than guessed, because picking
+ * a lane silently would act on the wrong entity.
+ */
+const splitCatalogIds = (requested, available) => {
+    const components = new Set(available.component);
+    const patterns = new Set(available.pattern);
+    const lanes = { component: [], pattern: [] };
+    const unknown = [];
+    const ambiguous = [];
+    for (const id of requested) {
+        const isComponent = components.has(id);
+        const isPattern = patterns.has(id);
+        if (isComponent && isPattern) {
+            ambiguous.push(id);
+        }
+        else if (isComponent) {
+            lanes.component.push(id);
+        }
+        else if (isPattern) {
+            lanes.pattern.push(id);
+        }
+        else {
+            unknown.push(id);
+        }
+    }
+    return { lanes, unknown, ambiguous };
+};
+exports.splitCatalogIds = splitCatalogIds;
+/** Quote ids for an error message: `"button", "card"`. */
+const quoteIds = (ids) => ids.map((id) => `"${id}"`).join(', ');
+exports.quoteIds = quoteIds;

package/dist/store/filesystem.d.ts

@@ -1,7 +1,7 @@
 /**
  * Filesystem-backed implementation of the normalized store abstraction.
  *
- * It is a thin read view over the already-resolved `runtimeConfig.entries`, so the records it
+ * It is a thin read view over the already-resolved `runtimeConfig.entities`, so the records it
  * returns are the same normalized component/pattern records the build consumes today — discovery
  * and normalization (modern `*.handoff.*` + legacy `{dirname}.*`, react/handlebars/csf/plain-object
  * declarations, CSF story discovery, `entries` resolution) all happen upstream in

package/dist/store/filesystem.js

@@ -2,7 +2,7 @@
 /**
  * Filesystem-backed implementation of the normalized store abstraction.
  *
- * It is a thin read view over the already-resolved `runtimeConfig.entries`, so the records it
+ * It is a thin read view over the already-resolved `runtimeConfig.entities`, so the records it
  * returns are the same normalized component/pattern records the build consumes today — discovery
  * and normalization (modern `*.handoff.*` + legacy `{dirname}.*`, react/handlebars/csf/plain-object
  * declarations, CSF story discovery, `entries` resolution) all happen upstream in
@@ -42,8 +42,8 @@ class FilesystemComponentStore {
         this.context = context;
     }
     get records() {
-        var _a, _b, _c;
-        return (_c = (_b = (_a = this.context.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;
+        return (_b = (_a = this.context.runtimeConfig) === null || _a === void 0 ? void 0 : _a.entities.components) !== null && _b !== void 0 ? _b : {};
     }
     list() {
         return Object.values(this.records);
@@ -68,8 +68,8 @@ class FilesystemPatternStore {
         this.context = context;
     }
     get records() {
-        var _a, _b, _c;
-        return (_c = (_b = (_a = this.context.runtimeConfig) === null || _a === void 0 ? void 0 : _a.entries) === null || _b === void 0 ? void 0 : _b.patterns) !== null && _c !== void 0 ? _c : {};
+        var _a, _b;
+        return (_b = (_a = this.context.runtimeConfig) === null || _a === void 0 ? void 0 : _a.entities.patterns) !== null && _b !== void 0 ? _b : {};
     }
     list() {
         return Object.values(this.records);
@@ -116,8 +116,8 @@ class FilesystemPageStore {
         this.context = context;
     }
     get records() {
-        var _a, _b, _c;
-        return (_c = (_b = (_a = this.context.runtimeConfig) === null || _a === void 0 ? void 0 : _a.entries) === null || _b === void 0 ? void 0 : _b.pages) !== null && _c !== void 0 ? _c : {};
+        var _a, _b;
+        return (_b = (_a = this.context.runtimeConfig) === null || _a === void 0 ? void 0 : _a.entities.pages) !== null && _b !== void 0 ? _b : {};
     }
     list() {
         return Object.values(this.records);

package/dist/store/registry.js

@@ -23,6 +23,17 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
         step((generator = generator.apply(thisArg, _arguments || [])).next());
     });
 };
+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 __asyncValues = (this && this.__asyncValues) || function (o) {
     if (!Symbol.asyncIterator) throw new TypeError("Symbol.asyncIterator is not defined.");
     var m = o[Symbol.asyncIterator], i;
@@ -32,6 +43,7 @@ var __asyncValues = (this && this.__asyncValues) || function (o) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createRegistryStore = exports.RegistryAssetStore = exports.RegistryTokenStore = exports.filterPublishedPageIds = exports.searchPageCandidates = exports.RegistryPageStore = exports.RegistryPatternStore = exports.RegistryComponentStore = void 0;
+const previews_1 = require("../catalog/previews");
 const drizzle_orm_1 = require("drizzle-orm");
 const schema_1 = require("../registry/db/schema");
 /**
@@ -52,6 +64,16 @@ const toTextFileResource = (row) => {
         contentType: row.contentType,
     };
 };
+/**
+ * Restore source order after jsonb storage without exposing transfer-only metadata. `entries` and
+ * `componentExport` describe the publisher's source layout and exist for checkout. The workspace
+ * has no equivalent, so the docs API must not serve them.
+ */
+const readComponentRecord = (record) => {
+    var _a;
+    const { previewOrder, entries, componentExport } = record, item = __rest(record, ["previewOrder", "entries", "componentExport"]);
+    return Object.assign(Object.assign({}, item), { previews: (0, previews_1.orderPreviews)((_a = item.previews) !== null && _a !== void 0 ? _a : {}, previewOrder !== null && previewOrder !== void 0 ? previewOrder : []) });
+};
 class RegistryComponentStore {
     constructor(context) {
         this.context = context;
@@ -59,14 +81,13 @@ class RegistryComponentStore {
     list() {
         return __awaiter(this, void 0, void 0, function* () {
             const rows = yield this.context.db.select({ record: schema_1.components.record }).from(schema_1.components);
-            return rows.map((row) => row.record);
+            return rows.map((row) => readComponentRecord(row.record));
         });
     }
     get(id) {
         return __awaiter(this, void 0, void 0, function* () {
-            var _a, _b;
             const rows = yield this.context.db.select({ record: schema_1.components.record }).from(schema_1.components).where((0, drizzle_orm_1.eq)(schema_1.components.id, id)).limit(1);
-            return (_b = (_a = rows[0]) === null || _a === void 0 ? void 0 : _a.record) !== null && _b !== void 0 ? _b : null;
+            return rows[0] ? readComponentRecord(rows[0].record) : null;
         });
     }
     /**

package/dist/transformers/plugins/csf-render.js

@@ -19,6 +19,7 @@ const path_1 = __importDefault(require("path"));
 const react_1 = __importDefault(require("react"));
 const server_1 = __importDefault(require("react-dom/server"));
 const react_element_to_jsx_string_1 = __importDefault(require("react-element-to-jsx-string"));
+const catalog_1 = require("../../catalog");
 const logger_1 = require("../../utils/logger");
 const docgen_1 = require("../docgen");
 const component_1 = require("../preview/component");
@@ -304,8 +305,9 @@ function csfRenderPlugin(componentData, _documentationComponents, handoff) {
                 const generatedProperties = Object.assign({}, explicitProperties);
                 const incomingPreviews = Object.assign({}, (componentData.previews || {}));
                 const patternPreviews = Object.fromEntries(Object.entries(incomingPreviews).filter(([key]) => key.startsWith('__pattern_')));
-                // Include all named stories as previews and preserve injected pattern previews.
-                componentData.previews = Object.assign(Object.assign({}, (0, csf_1.createCsfStoryPreviews)(moduleExports)), patternPreviews);
+                // Include all named stories as previews and preserve injected pattern previews. Story order
+                // comes from the source text: esbuild emits its export map alphabetically.
+                componentData.previews = Object.assign(Object.assign({}, (0, catalog_1.orderPreviews)((0, csf_1.createCsfStoryPreviews)(moduleExports), (0, catalog_1.readExportOrderFromSource)(sourceCode))), patternPreviews);
                 for (const [storyKey, storyValue] of stories) {
                     const storyObj = (typeof storyValue === 'function' ? {} : storyValue);
                     const mergedArgs = Object.assign(Object.assign({}, (meta.args || {})), (storyObj.args || {}));

package/dist/transformers/plugins/ssr-render.js

@@ -49,6 +49,13 @@ const PLUGIN_CONSTANTS = {
 const CLIENT_ARTIFACT_SUFFIX = 'client.js';
 /** Logical artifact path of a component's client/hydration bundle. */
 const clientArtifactPath = (componentId) => `component/${componentId}.${CLIENT_ARTIFACT_SUFFIX}`;
+function selectComponentExport(moduleExports, exportName) {
+    var _a;
+    if (exportName && exportName !== 'default' && (moduleExports === null || moduleExports === void 0 ? void 0 : moduleExports[exportName])) {
+        return moduleExports[exportName];
+    }
+    return (_a = moduleExports === null || moduleExports === void 0 ? void 0 : moduleExports.default) !== null && _a !== void 0 ? _a : null;
+}
 /**
  * Loads and processes component schema using hierarchical approach
  * @param componentData - Component transformation data
@@ -70,7 +77,7 @@ function loadComponentSchemaAndModule(componentData, componentPath, handoff) {
         if (!((_b = componentData.entries) === null || _b === void 0 ? void 0 : _b.schema)) {
             try {
                 const moduleExports = yield (0, module_1.buildAndEvaluateModule)(componentPath, handoff);
-                component = moduleExports.exports.default;
+                component = selectComponentExport(moduleExports.exports, componentData.componentExport);
                 // Try to load schema from component exports
                 properties = yield (0, schema_loader_1.loadSchemaFromComponent)(moduleExports.exports, handoff);
                 // If no schema found, use shared docgen fallback
@@ -86,7 +93,7 @@ function loadComponentSchemaAndModule(componentData, componentPath, handoff) {
         if (!component) {
             try {
                 const moduleExports = yield (0, module_1.buildAndEvaluateModule)(componentPath, handoff);
-                component = moduleExports.exports.default;
+                component = selectComponentExport(moduleExports.exports, componentData.componentExport);
             }
             catch (error) {
                 logger_1.Logger.error(`Failed to load component for rendering "${componentPath}":`, error);
@@ -111,13 +118,15 @@ function loadComponentSchemaAndModule(componentData, componentPath, handoff) {
  *
  * @param componentId - Component identifier used to match pattern mount points to this bundle
  * @param componentPath - Path to the component file
+ * @param componentExport - Export holding the implementation; the default export when absent
  * @returns Client-side hydration source code
  */
-function generateClientHydrationSource(componentId, componentPath) {
+function generateClientHydrationSource(componentId, componentPath, componentExport) {
+    const importClause = componentExport && componentExport !== 'default' ? `{ ${componentExport} as Component }` : 'Component';
     return `
     import React from 'react';
     import { hydrateRoot } from 'react-dom/client';
-    import Component from '${(0, vite_1.normalizePath)(componentPath)}';
+    import ${importClause} from '${(0, vite_1.normalizePath)(componentPath)}';
 
     const parseProps = (propsId) => {
       const raw = propsId ? document.getElementById(propsId)?.textContent : '{}';
@@ -266,7 +275,7 @@ function ssrRenderPlugin(componentData, documentationComponents, handoff) {
                 // `component/<id>.client.js` artifact. The hydration source only imports the component and
                 // reads props from the in-document `__APP_PROPS__` element, so it is identical across every
                 // preview of this component.
-                const clientHydrationSource = generateClientHydrationSource(componentId, componentPath);
+                const clientHydrationSource = generateClientHydrationSource(componentId, componentPath, componentData.componentExport);
                 const clientBuildConfig = Object.assign(Object.assign({}, build_1.DEFAULT_CLIENT_BUILD_CONFIG), { logLevel: 'silent', stdin: {
                         contents: clientHydrationSource,
                         resolveDir: process.cwd(),

package/dist/transformers/preview/component/api.d.ts

@@ -1,5 +1,13 @@
 import Handoff from '../../../index';
 import { ComponentListObject, TransformComponentTokensResult } from '../types';
+/**
+ * Strip the fields that must not reach the written artifact.
+ *
+ * The docs API serves this artifact publicly, and publish uploads it verbatim. An absolute path in
+ * the artifact exposes the filesystem layout of the build machine, so this drops the workspace
+ * locations `path` and `entries`. The build takes those locations from the runtime config, and
+ * publish remaps `entries` onto the registry record.
+ */
 export declare const sanitizeComponentApiData: (component: TransformComponentTokensResult) => TransformComponentTokensResult;
 export declare const getAPIPath: (handoff: Handoff) => string;
 export declare const writeComponentApi: (id: string, component: TransformComponentTokensResult, handoff: Handoff, preserveKeys?: string[]) => Promise<void>;