handoff-app 2.0.0-5 → 2.0.0-7

package/src/registry/db/schema.ts

@@ -108,6 +108,8 @@ export const components = pgTable(
     group: text('group'),
     type: text('type'),
     renderer: text('renderer'),
+    /** How the implementation file is written (`csf`), when the renderer alone does not say. */
+    sourceFormat: text('source_format'),
     tags: jsonb('tags').$type<string[]>(),
     categories: jsonb('categories').$type<string[]>(),
     /** Full normalized component record. */

package/src/registry/publish/index.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
@@ -18,7 +19,7 @@ import { Logger } from '../../utils/logger';
 import { createRegistryClient, RegistryClientError, type RegistryClient } from '../client';
 import { resolveAuthenticatedRegistryConnection } from '../connection';
 import type { EntitySummary, TransferEntityKind } from '../transfer';
-import { selectIds } from '../selection';
+import { quoteIds, selectIds, splitCatalogIds } from '../selection';
 import { describePublishError, describeUploadFailure } from './errors';
 import { assertRequiredArtifactsPresent, buildPublishPackage, PublishPackageError } from './package';
 
@@ -45,6 +46,26 @@ export const assertPublishableWorkspace = (handoff: Handoff): void => {
   }
 };
 
+/** The entity lanes a catalog run visits, in dependency order: a pattern composes components. */
+const CATALOG_LANES = ['component', 'pattern'] as const;
+
+const isCatalogLane = (kind: TransferEntityKind): boolean => 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: Handoff): void => {
+  const duplicates = handoff.runtimeConfig?.duplicateCatalogIds ?? [];
+  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
@@ -103,7 +124,7 @@ const runTargetedBuild = async (handoff: Handoff, kind: TransferEntityKind, id:
   // 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 (!handoff.runtimeConfig?.entries?.pages?.[id]) {
+    if (!handoff.runtimeConfig?.entities.pages[id]) {
       throw new PublishPackageError(`Page "${id}" is not declared in this workspace.`);
     }
     return;
@@ -115,14 +136,14 @@ const runTargetedBuild = async (handoff: Handoff, kind: TransferEntityKind, id:
   await buildMainCss(handoff);
 
   if (kind === 'component') {
-    if (!handoff.runtimeConfig?.entries?.components?.[id]) {
+    if (!handoff.runtimeConfig?.entities.components[id]) {
       throw new PublishPackageError(`Component "${id}" is not declared in this workspace.`);
     }
     await processComponents(handoff, id);
     return;
   }
 
-  const pattern = handoff.runtimeConfig?.entries?.patterns?.[id];
+  const pattern = handoff.runtimeConfig?.entities.patterns[id];
   if (!pattern) {
     throw new PublishPackageError(`Pattern "${id}" is not declared in this workspace.`);
   }
@@ -130,7 +151,7 @@ const runTargetedBuild = async (handoff: Handoff, kind: TransferEntityKind, id:
   // then compose just this pattern.
   const referencedComponentIds = new Set(pattern.components.map((ref) => ref.id));
   for (const componentId of Array.from(referencedComponentIds)) {
-    if (handoff.runtimeConfig?.entries?.components?.[componentId]) {
+    if (handoff.runtimeConfig?.entities.components[componentId]) {
       await processComponents(handoff, componentId);
     }
   }
@@ -142,6 +163,7 @@ const runTargetedBuild = async (handoff: Handoff, kind: TransferEntityKind, id:
  * receive a targeted build, while pages are packaged directly from their source.
  */
 export const publishEntity = async (handoff: Handoff, kind: TransferEntityKind, id: string): Promise<void> => {
+  if (isCatalogLane(kind)) assertUniqueCatalogIds(handoff);
   const { client, url } = await resolveTransport(handoff);
 
   if (!handoff.skipBuild) {
@@ -218,24 +240,18 @@ const selectEntityIds = (available: string[], requested: string[] | undefined, k
 };
 
 /**
- * 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.
  */
-export const publishEntities = async (handoff: Handoff, kind: TransferEntityKind, ids?: string[]): Promise<void> => {
-  const { client, url } = await resolveTransport(handoff);
-
-  if (!handoff.skipBuild) {
-    Logger.info(`Building ${kind}s for publish…`);
-    await runBulkBuild(handoff, kind);
-  }
-
+const uploadEntities = async (handoff: Handoff, transport: PublishTransport, kind: TransferEntityKind, ids?: string[]): Promise<number> => {
+  const { client, url } = transport;
   const targets = selectEntityIds(await listWorkspaceEntityIds(handoff, kind), ids, kind);
   if (targets.length === 0) {
     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.
@@ -281,10 +297,91 @@ export const publishEntities = async (handoff: Handoff, kind: TransferEntityKind
     `${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.error(`  - ${failure.id}: ${failure.message}`);
-    }
-    throw new PublishError(`${failed.length} ${kind}(s) failed to publish.`);
+  for (const failure of failed) {
+    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.
+ */
+export const publishEntities = async (handoff: Handoff, kind: TransferEntityKind, ids?: string[]): Promise<void> => {
+  if (isCatalogLane(kind)) assertUniqueCatalogIds(handoff);
+  const transport = await resolveTransport(handoff);
+
+  if (!handoff.skipBuild) {
+    Logger.info(`Building ${kind}s for publish…`);
+    await runBulkBuild(handoff, kind);
+  }
+
+  const failed = await uploadEntities(handoff, transport, kind, ids);
+  if (failed > 0) {
+    throw new PublishError(`${failed} ${kind}(s) failed to publish.`);
+  }
+};
+
+/**
+ * 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 = async (handoff: Handoff, ids?: string[]): Promise<{ kind: TransferEntityKind; ids?: string[] }[]> => {
+  if (!ids) {
+    return CATALOG_LANES.map((kind) => ({ kind }));
+  }
+
+  const available = {
+    component: await listWorkspaceEntityIds(handoff, 'component'),
+    pattern: await listWorkspaceEntityIds(handoff, 'pattern'),
+  };
+  const { lanes, unknown, ambiguous } = splitCatalogIds(ids, available);
+
+  if (ambiguous.length > 0) {
+    throw new PublishError(
+      `${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 ${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.
+ */
+export const publishCatalog = async (handoff: Handoff, ids?: string[]): Promise<void> => {
+  assertUniqueCatalogIds(handoff);
+  const transport = await resolveTransport(handoff);
+  const lanes = await resolveCatalogLanes(handoff, ids);
+
+  if (!handoff.skipBuild) {
+    Logger.info('Building catalog items for publish…');
+    // The pattern build runs the component build first, so one call covers both lanes.
+    await runBulkBuild(handoff, 'pattern');
+  }
+
+  let failed = 0;
+  for (const lane of lanes) {
+    failed += await uploadEntities(handoff, transport, lane.kind, lane.ids);
+  }
+  if (failed > 0) {
+    throw new PublishError(`${failed} catalog item(s) failed to publish.`);
   }
 };

package/src/registry/publish/package.ts

@@ -33,7 +33,8 @@ export class PublishPackageError extends Error {
 type RenderedEntityKind = Extract<TransferEntityKind, 'component' | 'pattern'>;
 
 /**
- * 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.
@@ -58,6 +59,18 @@ const enrichItem = async (
     item.renderer = renderer;
   }
 
+  const sourceFormat = (runtime as { sourceFormat?: string }).sourceFormat;
+  if (sourceFormat) {
+    item.sourceFormat = sourceFormat;
+  }
+
+  const componentExport = (runtime as ComponentListObject).componentExport;
+  if (componentExport) item.componentExport = componentExport;
+  if (kind === 'component') {
+    // PostgreSQL jsonb does not preserve object key order.
+    item.previewOrder = Object.keys((runtime as ComponentListObject).previews ?? {});
+  }
+
   if (rawEntries && sourceDir) {
     const remapped: Record<string, string> = {};
     for (const [key, value] of Object.entries(rawEntries)) {

package/src/registry/selection.ts

@@ -4,6 +4,9 @@
  * 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. */
@@ -17,3 +20,44 @@ export const selectIds = (available: string[], requested?: string[]): { selected
     unknown: requested.filter((id) => !availableIds.has(id)),
   };
 };
+
+/** 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 const splitCatalogIds = (
+  requested: string[],
+  available: CatalogLanes
+): { lanes: CatalogLanes; unknown: string[]; ambiguous: string[] } => {
+  const components = new Set(available.component);
+  const patterns = new Set(available.pattern);
+  const lanes: CatalogLanes = { component: [], pattern: [] };
+  const unknown: string[] = [];
+  const ambiguous: string[] = [];
+
+  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 };
+};
+
+/** Quote ids for an error message: `"button", "card"`. */
+export const quoteIds = (ids: string[]): string => ids.map((id) => `"${id}"`).join(', ');

package/src/store/filesystem.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
@@ -71,7 +71,7 @@ export class FilesystemComponentStore implements ComponentStore {
   constructor(private readonly context: FilesystemStoreContext) {}
 
   private get records(): Record<string, ComponentListObject> {
-    return this.context.runtimeConfig?.entries?.components ?? {};
+    return this.context.runtimeConfig?.entities.components ?? {};
   }
 
   list(): ComponentListObject[] {
@@ -97,7 +97,7 @@ export class FilesystemPatternStore implements PatternStore {
   constructor(private readonly context: FilesystemStoreContext) {}
 
   private get records(): Record<string, PatternListObject> {
-    return this.context.runtimeConfig?.entries?.patterns ?? {};
+    return this.context.runtimeConfig?.entities.patterns ?? {};
   }
 
   list(): PatternListObject[] {
@@ -145,7 +145,7 @@ export class FilesystemPageStore implements PageStore {
   constructor(private readonly context: FilesystemStoreContext) {}
 
   private get records(): Record<string, PageListObject> {
-    return this.context.runtimeConfig?.entries?.pages ?? {};
+    return this.context.runtimeConfig?.entities.pages ?? {};
   }
 
   list(): PageListObject[] {

package/src/store/registry.ts

@@ -14,6 +14,7 @@
  *   returned exactly as it was published.
  */
 
+import { orderPreviews } from '../catalog/previews';
 import { and, eq, inArray, or, sql, type SQLWrapper } from 'drizzle-orm';
 import type { AssetStorage, AssetStorageReadResult } from '../registry/asset-storage/types';
 import type { RegistryDatabase } from '../registry/db/client';
@@ -86,17 +87,27 @@ const toTextFileResource = (row: RegistryFileRow): TextFileResource | null => {
   };
 };
 
+/**
+ * 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: ComponentListObject): ComponentListObject => {
+  const { previewOrder, entries, componentExport, ...item } = record;
+  return { ...item, previews: orderPreviews(item.previews ?? {}, previewOrder ?? []) };
+};
+
 export class RegistryComponentStore implements ComponentStore {
   constructor(private readonly context: RegistryStoreContext) {}
 
   async list(): Promise<ComponentListObject[]> {
     const rows = await this.context.db.select({ record: components.record }).from(components);
-    return rows.map((row) => row.record);
+    return rows.map((row) => readComponentRecord(row.record));
   }
 
   async get(id: string): Promise<ComponentListObject | null> {
     const rows = await this.context.db.select({ record: components.record }).from(components).where(eq(components.id, id)).limit(1);
-    return rows[0]?.record ?? null;
+    return rows[0] ? readComponentRecord(rows[0].record) : null;
   }
 
   /**

package/src/transformers/plugins/csf-render.ts

@@ -7,6 +7,7 @@ import ReactDOMServer from 'react-dom/server';
 import reactElementToJSXString from 'react-element-to-jsx-string';
 import { Plugin } from 'vite';
 import Handoff from '../..';
+import { orderPreviews, readExportOrderFromSource } from '../../catalog';
 import { Logger } from '../../utils/logger';
 import { generateDocsArtifact, getPropertiesForComponentFromDocs } from '../docgen';
 import { SlotMetadata, SlotType } from '../preview/component';
@@ -358,9 +359,10 @@ export function csfRenderPlugin(
         Object.entries(incomingPreviews).filter(([key]) => key.startsWith('__pattern_'))
       );
 
-      // Include all named stories as previews and preserve injected pattern previews.
+      // 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 = {
-        ...createCsfStoryPreviews(moduleExports),
+        ...orderPreviews(createCsfStoryPreviews(moduleExports), readExportOrderFromSource(sourceCode)),
         ...patternPreviews,
       };
 

package/src/transformers/plugins/ssr-render.ts

@@ -60,6 +60,13 @@ const CLIENT_ARTIFACT_SUFFIX = 'client.js';
 /** Logical artifact path of a component's client/hydration bundle. */
 const clientArtifactPath = (componentId: string): string => `component/${componentId}.${CLIENT_ARTIFACT_SUFFIX}`;
 
+function selectComponentExport(moduleExports: Record<string, any>, exportName?: string): ReactComponent | null {
+  if (exportName && exportName !== 'default' && moduleExports?.[exportName]) {
+    return moduleExports[exportName];
+  }
+  return moduleExports?.default ?? null;
+}
+
 /**
  * Loads and processes component schema using hierarchical approach
  * @param componentData - Component transformation data
@@ -85,7 +92,7 @@ async function loadComponentSchemaAndModule(
   if (!componentData.entries?.schema) {
     try {
       const moduleExports = await buildAndEvaluateModule(componentPath, handoff);
-      component = moduleExports.exports.default;
+      component = selectComponentExport(moduleExports.exports, componentData.componentExport);
 
       // Try to load schema from component exports
       properties = await loadSchemaFromComponent(moduleExports.exports, handoff);
@@ -103,7 +110,7 @@ async function loadComponentSchemaAndModule(
   if (!component) {
     try {
       const moduleExports = await buildAndEvaluateModule(componentPath, handoff);
-      component = moduleExports.exports.default;
+      component = selectComponentExport(moduleExports.exports, componentData.componentExport);
     } catch (error) {
       Logger.error(`Failed to load component for rendering "${componentPath}":`, error);
       return [null, null];
@@ -128,13 +135,16 @@ async function loadComponentSchemaAndModule(
  *
  * @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: string, componentPath: string): string {
+function generateClientHydrationSource(componentId: string, componentPath: string, componentExport?: string): string {
+  const importClause = componentExport && componentExport !== 'default' ? `{ ${componentExport} as Component }` : 'Component';
+
   return `
     import React from 'react';
     import { hydrateRoot } from 'react-dom/client';
-    import Component from '${normalizePath(componentPath)}';
+    import ${importClause} from '${normalizePath(componentPath)}';
 
     const parseProps = (propsId) => {
       const raw = propsId ? document.getElementById(propsId)?.textContent : '{}';
@@ -304,7 +314,7 @@ export function ssrRenderPlugin(
       // `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 = {
         ...DEFAULT_CLIENT_BUILD_CONFIG,
         logLevel: 'silent' as const,

package/src/transformers/preview/component/api.ts

@@ -5,6 +5,14 @@ import Handoff from '../../../index';
 import { ComponentListObject, TransformComponentTokensResult } from '../types';
 import { getDocumentedPreviews } from './previews';
 
+/**
+ * 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 const sanitizeComponentApiData = (
   component: TransformComponentTokensResult
 ): TransformComponentTokensResult => {
@@ -13,9 +21,11 @@ export const sanitizeComponentApiData = (
   const sanitized = {
     ...component,
     previews: getDocumentedPreviews(component.previews),
-  };
+  } as NonNullable<TransformComponentTokensResult> & { path?: string };
 
   delete sanitized.internalPatternPreviews;
+  delete sanitized.entries;
+  delete sanitized.path;
 
   return sanitized;
 };
@@ -150,6 +160,8 @@ export const readComponentMetadataApi = async (handoff: Handoff, id: string): Pr
     properties: componentData.properties,
     previews: getDocumentedPreviews(componentData.previews),
     path: buildComponentDetailUrl(id, process.env.HANDOFF_APP_BASE_PATH ?? ''),
+    ...(componentData.renderer ? { renderer: componentData.renderer } : {}),
+    ...(componentData.sourceFormat ? { sourceFormat: componentData.sourceFormat } : {}),
   };
 };
 export default writeComponentApi;

package/src/transformers/preview/component/artifacts.ts

@@ -16,7 +16,7 @@ const CLIENT_ARTIFACT_SUFFIX = '.client.js';
 export const getComponentApiPath = (handoff: Handoff) => path.resolve(getAPIPath(handoff), 'component');
 
 const getComponentPreviewKeys = async (handoff: Handoff, componentId: string): Promise<Set<string>> => {
-  const runtimeComponent = handoff.runtimeConfig?.entries?.components?.[componentId];
+  const runtimeComponent = handoff.runtimeConfig?.entities.components[componentId];
   const previewKeys = new Set<string>();
 
   const outputFilePath = path.resolve(getComponentApiPath(handoff), `${componentId}.json`);
@@ -67,15 +67,19 @@ export const removeComponentApi = async (handoff: Handoff, id: string): Promise<
   }
 };
 
-export const syncComponentArtifacts = async (handoff: Handoff): Promise<void> => {
+export const syncComponentArtifacts = async (handoff: Handoff, removedIds: readonly string[] = []): Promise<void> => {
   const componentPath = getComponentApiPath(handoff);
   await fs.ensureDir(componentPath);
 
-  const runtimeComponents = handoff.runtimeConfig?.entries?.components ?? {};
+  const runtimeComponents = handoff.runtimeConfig?.entities.components ?? {};
   const runtimeIds = Object.keys(runtimeComponents);
   const entries = await fs.readdir(componentPath);
 
-  const discoveredArtifactIds = new Set<string>(runtimeIds);
+  // `getArtifactComponentId` prunes a preview file only when it can name the owner. A deleted
+  // component is gone from the runtime config, and its `.json` is already removed, so nothing can
+  // match it. Naming it here restores the match without making its files valid. Every artifact it
+  // owns is then pruned, including the `__pattern_*` previews that the `.json` does not list.
+  const discoveredArtifactIds = new Set<string>([...runtimeIds, ...removedIds]);
   for (const entry of entries) {
     const parsed = path.parse(entry);
     if (parsed.ext === '.json' || parsed.ext === '.js' || parsed.ext === '.css') {

package/src/transformers/preview/component/builder.ts

@@ -1,6 +1,7 @@
 import { Types as CoreTypes } from 'handoff-core';
 import cloneDeep from 'lodash/cloneDeep';
 import { buildComponentDetailUrl } from '../../../artifacts/url';
+import type { SourceFormat } from '../../../catalog/renderers';
 import {
   BuildCache,
   checkOutputExists,
@@ -67,8 +68,16 @@ type ComponentBuildPlan = {
   validationMode: boolean;
 };
 
+/**
+ * A source format reads its previews out of the source file. A placeholder there is a preview
+ * nothing can render: the docs would offer a "Default" entry with no artifact. Only a renderer
+ * that renders whatever previews it is given needs the placeholder.
+ */
+const ownsItsPreviews = (data: { sourceFormat?: SourceFormat } | undefined): boolean => !!data?.sourceFormat;
+
 const ensureDefaultPreview = (data: TransformComponentTokensResult): void => {
   if (!data) return;
+  if (ownsItsPreviews(data)) return;
   if (!data.previews || Object.keys(data.previews).length === 0) {
     data.previews = {
       default: {
@@ -180,7 +189,7 @@ export async function processComponents(
   const documentationObject = await handoff.getDocumentationObject();
   const components = documentationObject?.components ?? ({} as CoreTypes.IDocumentationObject['components']);
   // Resolve the component set through the storage-agnostic store (v2). The filesystem store is a
-  // read view over `runtimeConfig.entries.components`, so these are the same records the build has
+  // read view over `runtimeConfig.entities.components`, so these are the same records the build has
   // always used — rebuilt into the id-keyed map the build logic below expects.
   const runtimeComponents: Record<string, ComponentListObject> = {};
   for (const component of await handoff.store.components.list()) {
@@ -191,7 +200,7 @@ export async function processComponents(
   if (id && !runtimeComponents[id]) {
     await removeComponentApi(handoff, id);
     await removeComponentFromSummaryApi(handoff, id);
-    await syncComponentArtifacts(handoff);
+    await syncComponentArtifacts(handoff, [id]);
     return [];
   }
 
@@ -302,7 +311,7 @@ export async function processComponents(
     // If this is NOT a figma component, add the default generic preview.
     // We add it here (before merge) so that if the user explicitly provided previews in 'restMetadata',
     // those will override this default (standard "config overrides defaults" behavior).
-    if (!restMetadata.figmaComponentId) {
+    if (!restMetadata.figmaComponentId && !ownsItsPreviews(restMetadata)) {
       componentDefaults.previews = {
         default: {
           title: 'Default',
@@ -337,12 +346,14 @@ export async function processComponents(
         data.css = existingData.css;
         data.sass = existingData.sass;
       }
-      // If we're not building previews, preserve pre-existing HTML, code snippet, usage, and previews.
+      // If we're not building previews, preserve pre-existing HTML, code snippet, usage, previews,
+      // and the code language they were rendered in.
       if (!buildPlan.previews) {
         data.html = existingData.html;
         data.code = existingData.code;
         data.usage = existingData.usage;
         data.previews = existingData.previews;
+        data.format = existingData.format;
       }
       /**
        * Always keep validation results from the previous data,
@@ -466,6 +477,8 @@ const buildComponentSummary = (id: string, data: TransformComponentTokensResult)
     properties: data.properties,
     previews: getDocumentedPreviews(data.previews),
     path: buildComponentDetailUrl(id, process.env.HANDOFF_APP_BASE_PATH ?? ''),
+    ...(data.renderer ? { renderer: data.renderer } : {}),
+    ...(data.sourceFormat ? { sourceFormat: data.sourceFormat } : {}),
   };
 };
 

package/src/transformers/preview/component/css.ts

@@ -1,7 +1,6 @@
 import fs from 'fs-extra';
 import path from 'path';
 import { InlineConfig, build as viteBuild } from 'vite';
-import { initRuntimeConfig } from '../../../config';
 import Handoff from '../../../index';
 import { formatDurationMs } from '../../../utils/duration';
 import { Logger } from '../../../utils/logger';
@@ -184,13 +183,13 @@ const buildComponentCss = async (data: TransformComponentTokensResult, handoff:
 export const buildMainCss = async (handoff: Handoff): Promise<void> => {
   const outputPath = getComponentOutputPath(handoff);
   const mainCssPath = path.resolve(outputPath, MAIN_COMPONENT_CSS_FILE);
-  const runtimeConfig = initRuntimeConfig(handoff)[0];
+  const scssEntry = handoff.runtimeConfig?.entries?.scss;
 
-  if (runtimeConfig?.entries?.scss && fs.existsSync(runtimeConfig.entries.scss)) {
-    const stat = await fs.stat(runtimeConfig.entries.scss);
-    const entryPath = stat.isDirectory() ? path.resolve(runtimeConfig.entries.scss, 'main.scss') : runtimeConfig.entries.scss;
+  if (scssEntry && fs.existsSync(scssEntry)) {
+    const stat = await fs.stat(scssEntry);
+    const entryPath = stat.isDirectory() ? path.resolve(scssEntry, 'main.scss') : scssEntry;
 
-    if (entryPath === runtimeConfig.entries.scss || fs.existsSync(entryPath)) {
+    if (entryPath === scssEntry || fs.existsSync(entryPath)) {
       Logger.info(`Building styles for global entry (${MAIN_COMPONENT_CSS_FILE})…`);
       const startedAt = Date.now();
       // Drop the previous artifact so a failed/empty rebuild cannot preserve stale global CSS that
@@ -198,15 +197,12 @@ export const buildMainCss = async (handoff: Handoff): Promise<void> => {
       await fs.remove(mainCssPath);
       try {
         const loadPaths = [
+          path.dirname(scssEntry),
           path.resolve(handoff.workingPath),
           path.resolve(handoff.workingPath, handoff.exportsDirectory, handoff.getProjectId()),
           path.resolve(handoff.workingPath, 'node_modules'),
         ];
 
-        if (handoff.runtimeConfig?.entries?.scss) {
-          loadPaths.unshift(path.dirname(handoff.runtimeConfig.entries.scss));
-        }
-
         await buildCssBundle({
           entry: entryPath,
           outputPath,