handoff-app 2.0.0-8 → 2.0.0-9

package/src/catalog/README.md

@@ -30,6 +30,9 @@ owns `fromCSF`, because CSF is a source format of React rather than a framework.
 The renderer entry points call `createCatalogItem` with their renderer. The pattern entry point calls it without a renderer.
 `define.ts` handles the shared `implementation` forms: a helper's `{ format, file }`, a file path, or an imported component.
 
+An entry point re-exports only the preview shape its renderer honors: `react.ts` exports `CatalogPreview` with `render`,
+`handlebars.ts` narrows it to reject `render`, and `pattern.ts` exports neither.
+
 A new renderer needs:
 
 - A `RENDERERS` row in `renderers.ts`

package/src/catalog/normalize.ts

@@ -101,6 +101,8 @@ export const normalizeCatalogItem = (moduleExports: Record<string, unknown>, opt
   entries[entryKey] = path.resolve(directory, source.file);
   // Existing builders consume template as the primary build input for every renderer.
   entries.template = entries[entryKey];
+  // The renderer and the hydration bundle both read a preview `render` from the declaration.
+  if (options.declarationPath) entries.declaration = options.declarationPath;
   // 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 = sourceForFile(source.file);

package/src/catalog/previews.ts

@@ -5,15 +5,17 @@ import type { CatalogPreview } from './types';
 
 /**
  * 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.
+ * re-exports, helper values. Accept only a plain object that owns one of the preview fields, 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 PREVIEW_KEYS = ['args', 'name', 'render'] as const;
+
 const isPreviewDeclaration = (value: unknown): boolean => {
   if (!value || typeof value !== 'object' || Array.isArray(value)) return false;
-  return Object.prototype.hasOwnProperty.call(value, 'args') || Object.prototype.hasOwnProperty.call(value, 'name');
+  return PREVIEW_KEYS.some((key) => Object.prototype.hasOwnProperty.call(value, key));
 };
 
 /** Matches an exported binding, an export list, or a CommonJS export assignment. */
@@ -104,6 +106,7 @@ export const createCatalogPreviews = (
       values: { ...(preview.args ?? {}) },
       url: preview.url ?? '',
       ...(preview.usage ? { usage: preview.usage } : {}),
+      ...(typeof preview.render === 'function' ? { render: preview.render as OptionalPreviewRender['render'] } : {}),
     };
   }
 

package/src/catalog/types.ts

@@ -53,6 +53,14 @@ export type CatalogPreview<TArgs = Record<string, unknown>> = {
   args?: TArgs;
   usage?: string;
   url?: string;
+  /**
+   * Renders this preview in place of the implementation, for props it cannot carry as data: an icon
+   * component, a callback, JSX children, or state the preview owns.
+   *
+   * Rendered as a component with `args`, so it can use hooks. The item still documents the
+   * implementation, so a wrapper never becomes the published API.
+   */
+  render?: (args: TArgs) => unknown;
 };
 
 /**

package/src/config/loader.ts

@@ -1,4 +1,5 @@
 import esbuild from 'esbuild';
+import { STYLE_IMPORT_LOADERS } from '../transformers/utils/build';
 import fs from 'fs-extra';
 import mergeWith from 'lodash/mergeWith';
 import { createRequire } from 'module';
@@ -67,6 +68,7 @@ const evaluateTypeScriptConfig = (filePath: string, handoffModulePath: string):
     target: 'node16',
     logLevel: 'silent',
     external: ['handoff-app'],
+    loader: STYLE_IMPORT_LOADERS,
   });
 
   const code = buildResult.outputFiles?.[0]?.text;

package/src/config/runtime.ts

@@ -1,4 +1,5 @@
 import esbuild from 'esbuild';
+import { STYLE_IMPORT_LOADERS } from '../transformers/utils/build';
 import fs from 'fs-extra';
 import { createRequire } from 'module';
 import path from 'path';
@@ -35,7 +36,8 @@ type DeclarationResolution = {
   fileName: string;
 };
 
-const DECLARATION_EXTENSIONS = ['ts', 'js', 'cjs'] as const;
+/** `.tsx`/`.jsx` are accepted so a preview can write its `render` as JSX. */
+const DECLARATION_EXTENSIONS = ['tsx', 'ts', 'jsx', 'js', 'cjs'] as const;
 
 const getDeclarationFiles = (componentBaseName: string): string[] =>
   DECLARATION_EXTENSIONS.map((ext) => `${componentBaseName}.handoff.${ext}`);
@@ -46,7 +48,7 @@ const findPreferredDeclaration = (componentDir: string, componentBaseName: strin
   if (exactMatch) return exactMatch;
 
   const allFiles = fs.existsSync(componentDir) ? fs.readdirSync(componentDir) : [];
-  const declarationFiles = allFiles.filter((file) => /\.handoff\.(ts|js|cjs)$/.test(file)).sort((a, b) => a.localeCompare(b));
+  const declarationFiles = allFiles.filter((file) => /\.handoff\.(tsx|ts|jsx|js|cjs)$/.test(file)).sort((a, b) => a.localeCompare(b));
 
   if (!declarationFiles.length) return undefined;
 
@@ -74,6 +76,7 @@ const evaluateDeclaration = (filePath: string, handoffModulePath: string): any =
     logLevel: 'silent',
     jsx: 'automatic',
     external: ['react', 'react-dom', 'handoff-app'],
+    loader: STYLE_IMPORT_LOADERS,
   });
 
   const code = buildResult.outputFiles?.[0]?.text;
@@ -219,7 +222,7 @@ export const initRuntimeConfig = (
     if (!declaration) {
       const declarationFiles = getDeclarationFiles(itemBaseName);
       Logger.warn(
-        `Missing catalog declaration (use .handoff.ts, .handoff.js, or .handoff.cjs; see UPGRADE.md#catalog-items): ${path.resolve(itemPath, declarationFiles.join(' or '))}`
+        `Missing catalog declaration (use .handoff.tsx, .handoff.ts, .handoff.jsx, .handoff.js, or .handoff.cjs; see UPGRADE.md#catalog-items): ${path.resolve(itemPath, declarationFiles.join(' or '))}`
       );
       continue;
     }
@@ -433,9 +436,9 @@ const injectPatternPreviews = (result: RuntimeConfig): void => {
 
       // Case 3: args present (with or without preview base) -> create synthetic preview
       let resolvedValues: Record<string, any> = {};
+      const basePreview = ref.preview ? component.previews?.[ref.preview] : undefined;
 
       if (ref.preview) {
-        const basePreview = component.previews?.[ref.preview];
         if (basePreview) {
           resolvedValues = { ...basePreview.values };
         } else {
@@ -454,6 +457,8 @@ const injectPatternPreviews = (result: RuntimeConfig): void => {
         values: resolvedValues,
         url: '',
         sourcePreview: ref.preview,
+        // The ref overrides arguments, not how the preview renders, so a base `render` still applies.
+        ...(basePreview?.render ? { render: basePreview.render } : {}),
       };
 
       ref.resolvedPreview = syntheticKey;

package/src/handlebars.ts

@@ -5,9 +5,15 @@
  * an argument type to check previews: `defineCatalogItem<BadgeArgs>`.
  */
 import { createCatalogItem } from './catalog/define';
-import type { CatalogItem, CatalogItemMeta } from './catalog/types';
+import type { CatalogItem, CatalogItemMeta, CatalogPreview as RendererPreview } from './catalog/types';
 
-export type { CatalogItem, CatalogItemMeta, CatalogPreview, CompositionRef, Preview, SourceDescriptor } from './catalog/types';
+export type { CatalogItem, CatalogItemMeta, CompositionRef, SourceDescriptor } from './catalog/types';
+
+/** A template renderer never calls a preview `render`, so declaring one is an error, not a no-op. */
+export type CatalogPreview<TArgs = Record<string, unknown>> = Omit<RendererPreview<TArgs>, 'render'> & { render?: never };
+
+/** Preview type for a Handlebars catalog item, with its argument type applied. */
+export type Preview<TItem> = TItem extends { readonly __args?: infer TArgs } ? CatalogPreview<Partial<NonNullable<TArgs>>> : never;
 
 /**
  * Declares a Handlebars catalog item. `implementation` is the path to its `.hbs` template. The

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

@@ -25,7 +25,7 @@ import {
   type SharedArtifactPresence,
 } from '../preview/component/shared-artifacts';
 import { TransformComponentTokensResult } from '../preview/types';
-import { DEFAULT_CLIENT_BUILD_CONFIG, createReactResolvePlugin } from '../utils/build';
+import { DEFAULT_CLIENT_BUILD_CONFIG, createReactResolvePlugin, withStyleLoaders } from '../utils/build';
 import { formatHtml, trimPreview } from '../utils/html';
 import { buildAndEvaluateModule } from '../utils/module';
 import { loadSchemaFromComponent, loadSchemaFromFile } from '../utils/schema-loader';
@@ -138,13 +138,31 @@ async function loadComponentSchemaAndModule(
  * @param componentExport - Export holding the implementation; the default export when absent
  * @returns Client-side hydration source code
  */
-function generateClientHydrationSource(componentId: string, componentPath: string, componentExport?: string): string {
+function generateClientHydrationSource(
+  componentId: string,
+  componentPath: string,
+  componentExport?: string,
+  declarationPath?: string
+): string {
   const importClause = componentExport && componentExport !== 'default' ? `{ ${componentExport} as Component }` : 'Component';
+  // A function cannot travel in the JSON props, so the client re-reads `render` from the module that
+  // defines it. Conditional, so an unaffected component does not ship its declaration's imports.
+  const declarationImport = declarationPath ? `import * as previewDeclaration from '${normalizePath(declarationPath)}';` : '';
+  const resolveComponent = declarationPath
+    ? `(mount) => {
+      const previewKey = mount.getAttribute('data-handoff-preview');
+      const render = previewKey ? previewDeclaration[previewKey]?.render : undefined;
+      return typeof render === 'function' ? render : Component;
+    }`
+    : '() => Component';
 
   return `
     import React from 'react';
     import { hydrateRoot } from 'react-dom/client';
     import ${importClause} from '${normalizePath(componentPath)}';
+    ${declarationImport}
+
+    const resolveComponent = ${resolveComponent};
 
     const parseProps = (propsId) => {
       const raw = propsId ? document.getElementById(propsId)?.textContent : '{}';
@@ -157,12 +175,14 @@ function generateClientHydrationSource(componentId: string, componentPath: strin
 
     const standaloneRoot = document.getElementById('${PLUGIN_CONSTANTS.ROOT_ELEMENT_ID}');
     if (standaloneRoot && !standaloneRoot.hasAttribute('data-handoff-component')) {
-      hydrateRoot(standaloneRoot, <Component {...parseProps('${PLUGIN_CONSTANTS.PROPS_SCRIPT_ID}')} />);
+      const StandaloneComponent = resolveComponent(standaloneRoot);
+      hydrateRoot(standaloneRoot, <StandaloneComponent {...parseProps('${PLUGIN_CONSTANTS.PROPS_SCRIPT_ID}')} />);
     }
 
     const patternMounts = document.querySelectorAll('[data-handoff-component=' + JSON.stringify('${componentId}') + ']');
     patternMounts.forEach((mount) => {
-      hydrateRoot(mount, <Component {...parseProps(mount.getAttribute('data-handoff-props'))} />);
+      const MountComponent = resolveComponent(mount);
+      hydrateRoot(mount, <MountComponent {...parseProps(mount.getAttribute('data-handoff-props'))} />);
     });
   `;
 }
@@ -175,12 +195,13 @@ function generateClientHydrationSource(componentId: string, componentPath: strin
  * artifact cannot be loaded.
  * @param componentId - Component identifier
  * @param previewTitle - Title for the preview
- * @param renderedHtml - Server-rendered HTML content
+ * @param renderedHtml - Server-rendered HTML, embedded verbatim so the client can hydrate it
  * @param props - Component props as JSON
  * @returns Complete HTML document
  */
 function generateHtmlDocument(
   componentId: string,
+  previewKey: string,
   previewTitle: string,
   renderedHtml: string,
   props: any,
@@ -220,7 +241,7 @@ function generateHtmlDocument(
     <title>${previewTitle}</title>
   </head>
   <body>
-    <div id="${PLUGIN_CONSTANTS.ROOT_ELEMENT_ID}">${renderedHtml}</div>
+    <div id="${PLUGIN_CONSTANTS.ROOT_ELEMENT_ID}" data-handoff-preview="${previewKey}">${renderedHtml}</div>
   </body>
 </html>`;
 }
@@ -314,7 +335,15 @@ 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, componentData.componentExport);
+      const declarationPath = Object.values(componentData.previews ?? {}).some((preview) => typeof preview.render === 'function')
+        ? componentData.entries?.declaration
+        : undefined;
+      const clientHydrationSource = generateClientHydrationSource(
+        componentId,
+        componentPath,
+        componentData.componentExport,
+        declarationPath
+      );
       const clientBuildConfig = {
         ...DEFAULT_CLIENT_BUILD_CONFIG,
         logLevel: 'silent' as const,
@@ -326,9 +355,10 @@ export function ssrRenderPlugin(
         plugins: [createReactResolvePlugin(handoff.workingPath, handoff.modulePath)],
       };
 
-      const finalClientBuildConfig = handoff.config?.hooks?.clientBuildConfig
+      const hookedClientBuildConfig = handoff.config?.hooks?.clientBuildConfig
         ? handoff.config.hooks.clientBuildConfig(clientBuildConfig)
         : clientBuildConfig;
+      const finalClientBuildConfig = withStyleLoaders(hookedClientBuildConfig);
 
       let clientBundleJs: string;
       try {
@@ -364,16 +394,23 @@ export function ssrRenderPlugin(
 
       // Generate previews for each variation
       for (const previewKey in componentData.previews) {
-        const previewProps = componentData.previews[previewKey].values;
-
-        // Server-side render the component
-        const serverRenderedHtml = ReactDOMServer.renderToString(React.createElement(ReactComponent, previewProps));
-        const formattedHtml = await formatHtml(serverRenderedHtml);
+        const preview = componentData.previews[previewKey];
+        const previewProps = preview.values;
+        // A synthetic pattern preview is not a named export, so the client looks up its
+        // `sourcePreview` instead. A preview without one has no `render` either.
+        const hydrationPreviewKey = preview.sourcePreview ?? previewKey;
+        // Rendered as a component rather than called, so a preview can use hooks and own state.
+        const PreviewComponent = (typeof preview.render === 'function' ? preview.render : ReactComponent) as ReactComponent;
+
+        // The markup must reach the document exactly as rendered. Formatting it adds text nodes React
+        // does not expect, so it discards the server markup and re-renders the preview on the client.
+        const serverRenderedHtml = ReactDOMServer.renderToString(React.createElement(PreviewComponent, previewProps));
 
         finalHtml = generateHtmlDocument(
           componentId,
-          componentData.previews[previewKey].title,
-          formattedHtml,
+          hydrationPreviewKey,
+          preview.title,
+          serverRenderedHtml,
           previewProps,
           sharedArtifacts,
           componentArtifacts
@@ -402,7 +439,7 @@ export function ssrRenderPlugin(
         });
       }
 
-      // Format final HTML and update component data
+      // The previews are already emitted, so this formats only the docs code view.
       finalHtml = await formatHtml(finalHtml);
       componentData.format = 'react';
       componentData.preview = '';

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

@@ -4,6 +4,7 @@ import { InlineConfig, build as viteBuild } from 'vite';
 import Handoff from '../../../index';
 import { formatDurationMs } from '../../../utils/duration';
 import { Logger } from '../../../utils/logger';
+import { collectStyleImports } from '../../utils/build';
 import viteBaseConfig from '../../vite-config';
 import { getComponentOutputPath } from '../component';
 import { TransformComponentTokensResult } from '../types';
@@ -98,14 +99,56 @@ const buildCssBundle = async ({
   }
 };
 
+const STYLE_SOURCE_EXTENSIONS = new Set(['.scss', '.sass', '.css']);
+
+/**
+ * The stylesheets of one item, in cascade order and deduplicated by resolved path.
+ *
+ * Discovered imports come first and the declared entry last, so a declared entry can override what
+ * the component imports. A project that both declares and imports one file must build it once.
+ */
+const resolveStyleSources = async (data: TransformComponentTokensResult, handoff: Handoff): Promise<string[]> => {
+  const template = data.entries?.template;
+  const discovered = template ? await collectStyleImports(path.resolve(template), handoff) : [];
+  const declared = data.entries?.scss ? [path.resolve(data.entries.scss)] : [];
+
+  const ordered: string[] = [];
+  const seen = new Set<string>();
+
+  for (const source of [...discovered, ...declared]) {
+    if (!seen.has(source) && STYLE_SOURCE_EXTENSIONS.has(path.extname(source)) && fs.existsSync(source)) {
+      seen.add(source);
+      ordered.push(source);
+    }
+  }
+
+  return ordered;
+};
+
+/**
+ * A single Sass entry that `@use`s every source in order.
+ *
+ * `@use` emits a repeated file once and inlines a plain `.css` source, which `@import` would leave
+ * as an unresolvable URL. Namespaces are explicit because two sources sharing a basename would
+ * claim the same default namespace and fail the compile.
+ */
+const writeCombinedStyleEntry = async (sources: string[], outputPath: string, id: string): Promise<string> => {
+  const entryPath = path.resolve(outputPath, `.${id}.entry.scss`);
+  const rules = sources.map((source, index) => `@use '${source.split(path.sep).join('/')}' as ns${index};`);
+
+  await fs.outputFile(entryPath, `${rules.join('\n')}\n`);
+
+  return entryPath;
+};
+
 const buildComponentCss = async (data: TransformComponentTokensResult, handoff: Handoff) => {
   const id = data.id;
   Logger.debug(`buildComponentCss`, id);
   const outputPath = getComponentOutputPath(handoff);
   const builtCssPath = path.resolve(outputPath, `${id}.css`);
-  const entry = data.entries?.scss;
+  const sources = await resolveStyleSources(data, handoff);
 
-  if (!entry) {
+  if (sources.length === 0) {
     // Keep generated output aligned with the current component declaration.
     await fs.remove(builtCssPath);
     delete data['css'];
@@ -114,64 +157,64 @@ const buildComponentCss = async (data: TransformComponentTokensResult, handoff:
     return data;
   }
 
-  const extension = path.extname(entry);
-
-  if (!extension) {
-    return data;
-  }
+  // A single source compiles directly, so its relative asset URLs and documented Sass stay as authored.
+  const combinedEntry = sources.length > 1 ? await writeCombinedStyleEntry(sources, outputPath, id) : undefined;
+  const entry = combinedEntry ?? sources[0];
 
   try {
-    if (extension === '.scss' || extension === '.css') {
-      // Remove the previous artifact before rebuilding so "no emitted CSS"
-      // doesn't silently preserve stale output from an earlier build.
-      await fs.remove(builtCssPath);
-
-      // Read the original source
-      const sourceContent = await fs.readFile(entry, 'utf8');
-      if (extension === '.scss') {
-        data['sass'] = sourceContent;
-      }
+    // Remove the previous artifact before rebuilding so "no emitted CSS"
+    // doesn't silently preserve stale output from an earlier build.
+    await fs.remove(builtCssPath);
+
+    // Read the original source
+    const primarySource = data.entries?.scss ? path.resolve(data.entries.scss) : sources[0];
+    if (path.extname(primarySource) === '.scss') {
+      data['sass'] = await fs.readFile(primarySource, 'utf8');
+    }
 
-      // Setup SASS load paths
-      const loadPaths = [
-        path.resolve(handoff.workingPath),
-        path.resolve(handoff.workingPath, handoff.exportsDirectory, handoff.getProjectId()),
-        path.resolve(handoff.workingPath, 'node_modules'),
-      ];
+    // Setup SASS load paths
+    const loadPaths = [
+      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));
-      }
+    if (handoff.runtimeConfig?.entries?.scss) {
+      loadPaths.unshift(path.dirname(handoff.runtimeConfig.entries.scss));
+    }
+
+    await buildCssBundle({
+      entry,
+      outputPath,
+      outputFilename: `${id}.css`,
+      loadPaths,
+      handoff,
+    });
 
-      await buildCssBundle({
-        entry,
-        outputPath,
-        outputFilename: `${id}.css`,
-        loadPaths,
-        handoff,
-      });
-
-      // Read the built CSS
-      if (fs.existsSync(builtCssPath)) {
-        const builtCss = await fs.readFile(builtCssPath, 'utf8');
-        data['css'] = builtCss;
-
-        // Handle shared styles — if the component SCSS uses the split marker,
-        // extract shared styles from the portion above it
-        const splitCSS = builtCss.split('/* COMPONENT STYLES*/');
-        if (splitCSS && splitCSS.length > 1) {
-          data['css'] = splitCSS[1];
-          data['sharedStyles'] = splitCSS[0];
-          await fs.writeFile(path.resolve(outputPath, SHARED_COMPONENT_CSS_FILE), data['sharedStyles']);
-        }
-      } else {
-        delete data['css'];
-        delete data['sharedStyles'];
+    // Read the built CSS
+    if (fs.existsSync(builtCssPath)) {
+      const builtCss = await fs.readFile(builtCssPath, 'utf8');
+      data['css'] = builtCss;
+
+      // Handle shared styles — if the component SCSS uses the split marker,
+      // extract shared styles from the portion above it
+      const splitCSS = builtCss.split('/* COMPONENT STYLES*/');
+      if (splitCSS && splitCSS.length > 1) {
+        data['css'] = splitCSS[1];
+        data['sharedStyles'] = splitCSS[0];
+        await fs.writeFile(path.resolve(outputPath, SHARED_COMPONENT_CSS_FILE), data['sharedStyles']);
       }
+    } else {
+      delete data['css'];
+      delete data['sharedStyles'];
     }
   } catch (e) {
     Logger.error(`Failed to build CSS for "${id}"`);
     throw e;
+  } finally {
+    if (combinedEntry) {
+      await fs.remove(combinedEntry);
+    }
   }
 
   return data;

package/src/transformers/preview/pattern/html.ts

@@ -56,7 +56,9 @@ export const composePatternHtml = (
       }
     }
 
-    const doc = parse(html);
+    // React SSR separates adjacent text children with `<!-- -->`. The parser drops comments by
+    // default, which would make every composed React fragment fail to hydrate.
+    const doc = parse(html, { comment: true });
     const suffix = `_p${i}`;
     const namespacedRootId = `root${suffix}`;
     const namespacedPropsId = `__APP_PROPS__${suffix}`;

package/src/transformers/preview/types.ts

@@ -18,6 +18,9 @@ export interface BasePageSlice {
   type: PageSliceType;
 }
 
+/** A fluid preview renders at the width the reader's stage has, so it is never scaled down. */
+export type PreviewWidth = 'fluid' | number;
+
 export interface BestPracticesPageSlice extends BasePageSlice {
   type: 'BEST_PRACTICES';
 }
@@ -27,6 +30,8 @@ export interface ComponentDisplayPageSlice extends BasePageSlice {
   showPreview?: boolean;
   showCodeHighlight?: boolean;
   defaultHeight?: string;
+  /** Viewport width for the preview, in pixels. Defaults to 'fluid'. */
+  defaultWidth?: PreviewWidth;
   filterBy?: Filter;
 }
 
@@ -115,6 +120,8 @@ export type ComponentObject = {
     story?: string;
     /** Optional path to schema file (if available) */
     schema?: string;
+    /** Declaration file path; a preview `render` is read from it at build and hydration time. */
+    declaration?: string;
     /** Optional path to templates directory */
     templates?: string;
   };
@@ -192,6 +199,8 @@ export type TransformComponentTokensResult = {
     story?: string;
     schema?: string;
     templates?: string;
+    /** See `ComponentObject.entries.declaration`. */
+    declaration?: string;
   };
   renderer?: RendererKind;
   /** See `ComponentObject.sourceFormat`. Distinct from `format`, the preview's code language. */
@@ -212,6 +221,11 @@ export type OptionalPreviewRender = {
   values: { [key: string]: string | string[] | any };
   url: string;
   usage?: string;
+  /**
+   * Build-time only: the server renders it and the client re-reads it from the declaration module.
+   * `JSON.stringify` drops it from published artifacts.
+   */
+  render?: (args: Record<string, any>) => unknown;
   /** Optional source preview/story key used to derive this preview */
   sourcePreview?: string;
 };

package/src/transformers/utils/build.ts

@@ -1,6 +1,21 @@
 import esbuild from 'esbuild';
 import path from 'path';
 
+const STYLE_EXTENSIONS = ['.css', '.scss', '.sass'];
+
+/**
+ * Keeps co-located stylesheet imports out of the JavaScript graph; the CSS pipeline compiles them.
+ *
+ * esbuild has no `.scss` loader, and a `.css` import fails too because these builds run with
+ * `write: false` and no output path. `empty` rather than a plugin: `esbuild.buildSync` rejects
+ * plugins, and the declaration and config loaders are synchronous.
+ *
+ * CSS Modules are not covered — the empty module leaves the class map undefined.
+ */
+export const STYLE_IMPORT_LOADERS: Record<string, esbuild.Loader> = Object.fromEntries(
+  STYLE_EXTENSIONS.map((extension) => [extension, 'empty' as esbuild.Loader])
+);
+
 /**
  * Default esbuild configuration for SSR builds
  */
@@ -11,6 +26,7 @@ export const DEFAULT_SSR_BUILD_CONFIG: esbuild.BuildOptions = {
   platform: 'node',
   jsx: 'automatic',
   external: ['react', 'react-dom', '@opentelemetry/api'],
+  loader: STYLE_IMPORT_LOADERS,
 };
 
 /**
@@ -24,8 +40,72 @@ export const DEFAULT_CLIENT_BUILD_CONFIG: esbuild.BuildOptions = {
   jsx: 'automatic',
   sourcemap: false,
   minify: false,
+  loader: STYLE_IMPORT_LOADERS,
 };
 
+/** Apply after a consumer hook: a hook that replaces `loader` would otherwise drop these. */
+export function withStyleLoaders<T extends esbuild.BuildOptions>(config: T): T {
+  return { ...config, loader: { ...config.loader, ...STYLE_IMPORT_LOADERS } };
+}
+
+/**
+ * Stylesheets of the module graph in cascade order: every import of a module before the module
+ * itself, siblings in source order.
+ *
+ * This is the order a bundler emits CSS in, and the cascade depends on it. A component that
+ * overrides a rule of a component it imports ties that rule on specificity, so the later of the
+ * two wins. esbuild's `onLoad` callbacks do not give this order: they fire roughly breadth-first,
+ * which puts a component's own stylesheet ahead of the ones it imports and reverses every such
+ * override.
+ */
+function orderStyleImports(metafile: esbuild.Metafile, entryPath: string): string[] {
+  const entryKey = Object.keys(metafile.inputs).find((key) => path.resolve(key) === entryPath);
+  if (!entryKey) return [];
+
+  const ordered: string[] = [];
+  const visited = new Set<string>();
+
+  const visit = (key: string) => {
+    if (visited.has(key)) return;
+    visited.add(key);
+
+    for (const imported of metafile.inputs[key]?.imports ?? []) {
+      if (!imported.external && metafile.inputs[imported.path]) visit(imported.path);
+    }
+
+    if (STYLE_EXTENSIONS.includes(path.extname(key))) ordered.push(path.resolve(key));
+  };
+
+  visit(entryKey);
+
+  return ordered;
+}
+
+/**
+ * Stylesheet paths imported anywhere in a component's module graph, in cascade order.
+ *
+ * An unbuildable graph yields an empty list rather than throwing, leaving the CSS step with the
+ * declared entry.
+ */
+export async function collectStyleImports(entryPath: string, handoff: any): Promise<string[]> {
+  const baseConfig: esbuild.BuildOptions = {
+    ...DEFAULT_SSR_BUILD_CONFIG,
+    entryPoints: [entryPath],
+    logLevel: 'silent',
+  };
+  const hookedConfig = handoff?.config?.hooks?.ssrBuildConfig ? handoff.config.hooks.ssrBuildConfig(baseConfig) : baseConfig;
+
+  try {
+    // The `empty` loader keeps stylesheets out of the JavaScript, and the metafile still records
+    // them as inputs, so the graph carries the order.
+    const result = await esbuild.build({ ...withStyleLoaders(hookedConfig), metafile: true });
+
+    return result.metafile ? orderStyleImports(result.metafile, entryPath) : [];
+  } catch {
+    return [];
+  }
+}
+
 /**
  * Resolves a module from multiple search directories
  * @param id - Module ID to resolve