handoff-app 2.0.0-8 → 2.0.0-9

package/README.md

@@ -74,17 +74,19 @@ The declaration supplies stable identity, documentation metadata, source entries
 
 ### React
 
-Handoff finds the implementation file from its import, so you do not need to repeat the path.
+Handoff finds the implementation file from its import, so you do not need to repeat the path, and
+builds the item's CSS from the stylesheets that import chain pulls in, descendants included.
 Previews are named exports. `Preview<typeof item>` gives them the implementation's argument type.
 
 ```tsx
 // components/example/Component.tsx
 export type ComponentProps = {
   label: string;
+  onSelect?: () => void;
 };
 
-export default function Component({ label }: ComponentProps) {
-  return <div>{label}</div>;
+export default function Component({ label, onSelect }: ComponentProps) {
+  return <div onClick={onSelect}>{label}</div>;
 }
 ```
 
@@ -112,6 +114,20 @@ export const Default = {
 
 The export name is the preview name. Use `name` to set a different display title.
 
+Arguments are serialized, so a preview that needs an icon, a callback, JSX children, or its own
+state declares `render` instead. It renders as a component, so a capitalized name lets it use hooks, and the item keeps
+documenting the implementation rather than a wrapper. Name a declaration that holds JSX
+`example.handoff.tsx`.
+
+```tsx
+export const Interactive = {
+  render: function Interactive() {
+    const [label, setLabel] = useState('Example');
+    return <Component label={label} onSelect={() => setLabel('Selected')} />;
+  },
+} satisfies ComponentPreview;
+```
+
 ### Handlebars
 
 The implementation is the path to the template. Arguments are `Record<string, unknown>` by default;

package/dist/catalog/normalize.js

@@ -88,6 +88,9 @@ const normalizeCatalogItem = (moduleExports, options) => {
     entries[entryKey] = path_1.default.resolve(directory, source.file);
     // Existing builders consume template as the primary build input for every renderer.
     entries.template = entries[entryKey];
+    // 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 = (0, renderers_1.sourceForFile)(source.file);

package/dist/catalog/previews.js

@@ -8,16 +8,17 @@ const fs_extra_1 = __importDefault(require("fs-extra"));
 const lodash_1 = require("lodash");
 /**
  * A declaration module exports more than previews: the item itself, the implementation it
- * re-exports, helper values. Accept only a plain object that owns `args` or `name`, so an exported
- * component or helper is never mistaken for a preview.
+ * 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'];
 const isPreviewDeclaration = (value) => {
     if (!value || typeof value !== 'object' || Array.isArray(value))
         return false;
-    return Object.prototype.hasOwnProperty.call(value, 'args') || Object.prototype.hasOwnProperty.call(value, 'name');
+    return PREVIEW_KEYS.some((key) => Object.prototype.hasOwnProperty.call(value, key));
 };
 /** Matches an exported binding, an export list, or a CommonJS export assignment. */
 const EXPORT_PATTERNS = [
@@ -99,7 +100,7 @@ const createCatalogPreviews = (moduleExports, declarationPath) => {
             throw new Error(`Preview "${exportName}" uses removed fields. Use args and name. See UPGRADE.md#catalog-items.`);
         }
         const preview = value;
-        previews[exportName] = Object.assign({ title: preview.name || (0, lodash_1.startCase)(exportName), values: Object.assign({}, ((_a = preview.args) !== null && _a !== void 0 ? _a : {})), url: (_b = preview.url) !== null && _b !== void 0 ? _b : '' }, (preview.usage ? { usage: preview.usage } : {}));
+        previews[exportName] = Object.assign(Object.assign({ title: preview.name || (0, lodash_1.startCase)(exportName), values: Object.assign({}, ((_a = preview.args) !== null && _a !== void 0 ? _a : {})), url: (_b = preview.url) !== null && _b !== void 0 ? _b : '' }, (preview.usage ? { usage: preview.usage } : {})), (typeof preview.render === 'function' ? { render: preview.render } : {}));
     }
     return declarationPath ? (0, exports.orderPreviews)(previews, (0, exports.readExportOrder)(declarationPath)) : previews;
 };

package/dist/catalog/types.d.ts

@@ -43,6 +43,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;
 };
 /**
  * `__args` exists only in the type system so `Preview<typeof item>` can infer the preview argument type.

package/dist/config/loader.js

@@ -5,6 +5,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.initConfig = exports.initConfigWithMetadata = exports.resolveProfileSelection = exports.HandoffConfigError = exports.CONFIG_FILE_PREFERENCE = void 0;
 const esbuild_1 = __importDefault(require("esbuild"));
+const build_1 = require("../transformers/utils/build");
 const fs_extra_1 = __importDefault(require("fs-extra"));
 const mergeWith_1 = __importDefault(require("lodash/mergeWith"));
 const module_1 = require("module");
@@ -40,6 +41,7 @@ const evaluateTypeScriptConfig = (filePath, handoffModulePath) => {
         target: 'node16',
         logLevel: 'silent',
         external: ['handoff-app'],
+        loader: build_1.STYLE_IMPORT_LOADERS,
     });
     const code = (_b = (_a = buildResult.outputFiles) === null || _a === void 0 ? void 0 : _a[0]) === null || _b === void 0 ? void 0 : _b.text;
     if (!code) {

package/dist/config/runtime.js

@@ -5,6 +5,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.toLowerCaseKeysAndValues = exports.getComponentsForPath = exports.isComponentDirectory = exports.initRuntimeConfig = exports.getCatalogItemDirectories = exports.resolveComponentDeclaration = void 0;
 const esbuild_1 = __importDefault(require("esbuild"));
+const build_1 = require("../transformers/utils/build");
 const fs_extra_1 = __importDefault(require("fs-extra"));
 const module_1 = require("module");
 const path_1 = __importDefault(require("path"));
@@ -17,7 +18,8 @@ const markdown_1 = require("../utils/markdown");
 const pages_1 = require("../utils/pages");
 const path_2 = require("../utils/path");
 const page_1 = require("./normalizers/page");
-const DECLARATION_EXTENSIONS = ['ts', 'js', 'cjs'];
+/** `.tsx`/`.jsx` are accepted so a preview can write its `render` as JSX. */
+const DECLARATION_EXTENSIONS = ['tsx', 'ts', 'jsx', 'js', 'cjs'];
 const getDeclarationFiles = (componentBaseName) => DECLARATION_EXTENSIONS.map((ext) => `${componentBaseName}.handoff.${ext}`);
 const findPreferredDeclaration = (componentDir, componentBaseName) => {
     const exactCandidates = getDeclarationFiles(componentBaseName);
@@ -25,7 +27,7 @@ const findPreferredDeclaration = (componentDir, componentBaseName) => {
     if (exactMatch)
         return exactMatch;
     const allFiles = fs_extra_1.default.existsSync(componentDir) ? fs_extra_1.default.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;
     for (const ext of DECLARATION_EXTENSIONS) {
@@ -52,6 +54,7 @@ const evaluateDeclaration = (filePath, handoffModulePath) => {
         logLevel: 'silent',
         jsx: 'automatic',
         external: ['react', 'react-dom', 'handoff-app'],
+        loader: build_1.STYLE_IMPORT_LOADERS,
     });
     const code = (_b = (_a = buildResult.outputFiles) === null || _a === void 0 ? void 0 : _a[0]) === null || _b === void 0 ? void 0 : _b.text;
     if (!code) {
@@ -178,7 +181,7 @@ const initRuntimeConfig = (handoff) => {
         const declaration = (0, exports.resolveComponentDeclaration)(itemPath, itemBaseName);
         if (!declaration) {
             const declarationFiles = getDeclarationFiles(itemBaseName);
-            logger_1.Logger.warn(`Missing catalog declaration (use .handoff.ts, .handoff.js, or .handoff.cjs; see UPGRADE.md#catalog-items): ${path_1.default.resolve(itemPath, declarationFiles.join(' or '))}`);
+            logger_1.Logger.warn(`Missing catalog declaration (use .handoff.tsx, .handoff.ts, .handoff.jsx, .handoff.js, or .handoff.cjs; see UPGRADE.md#catalog-items): ${path_1.default.resolve(itemPath, declarationFiles.join(' or '))}`);
             continue;
         }
         const declarationPath = path_1.default.resolve(itemPath, declaration.fileName);
@@ -361,8 +364,8 @@ const injectPatternPreviews = (result) => {
             }
             // Case 3: args present (with or without preview base) -> create synthetic preview
             let resolvedValues = {};
+            const basePreview = ref.preview ? (_b = component.previews) === null || _b === void 0 ? void 0 : _b[ref.preview] : undefined;
             if (ref.preview) {
-                const basePreview = (_b = component.previews) === null || _b === void 0 ? void 0 : _b[ref.preview];
                 if (basePreview) {
                     resolvedValues = Object.assign({}, basePreview.values);
                 }
@@ -374,12 +377,7 @@ const injectPatternPreviews = (result) => {
             resolvedValues = Object.assign(Object.assign({}, resolvedValues), ref.args);
             const syntheticKey = `__pattern_${patternId}_${i}`;
             component.internalPatternPreviews = component.internalPatternPreviews || {};
-            component.internalPatternPreviews[syntheticKey] = {
-                title: syntheticKey,
-                values: resolvedValues,
-                url: '',
-                sourcePreview: ref.preview,
-            };
+            component.internalPatternPreviews[syntheticKey] = Object.assign({ title: syntheticKey, values: resolvedValues, url: '', sourcePreview: ref.preview }, ((basePreview === null || basePreview === void 0 ? void 0 : basePreview.render) ? { render: basePreview.render } : {}));
             ref.resolvedPreview = syntheticKey;
             if (ref.resolved === undefined) {
                 ref.resolved = true;

package/dist/handlebars.d.ts

@@ -1,5 +1,13 @@
-import type { CatalogItem, CatalogItemMeta } from './catalog/types';
-export type { CatalogItem, CatalogItemMeta, CatalogPreview, CompositionRef, Preview, SourceDescriptor } from './catalog/types';
+import type { CatalogItem, CatalogItemMeta, CatalogPreview as RendererPreview } 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
  * renderer comes from this module, so the build fails an item whose file does not match it.

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

@@ -121,12 +121,25 @@ function loadComponentSchemaAndModule(componentData, componentPath, handoff) {
  * @param componentExport - Export holding the implementation; the default export when absent
  * @returns Client-side hydration source code
  */
-function generateClientHydrationSource(componentId, componentPath, componentExport) {
+function generateClientHydrationSource(componentId, componentPath, componentExport, declarationPath) {
     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 '${(0, vite_1.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 '${(0, vite_1.normalizePath)(componentPath)}';
+    ${declarationImport}
+
+    const resolveComponent = ${resolveComponent};
 
     const parseProps = (propsId) => {
       const raw = propsId ? document.getElementById(propsId)?.textContent : '{}';
@@ -139,12 +152,14 @@ function generateClientHydrationSource(componentId, componentPath, componentExpo
 
     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'))} />);
     });
   `;
 }
@@ -156,11 +171,11 @@ function generateClientHydrationSource(componentId, componentPath, componentExpo
  * 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, previewTitle, renderedHtml, props, sharedArtifacts, componentArtifacts) {
+function generateHtmlDocument(componentId, previewKey, previewTitle, renderedHtml, props, sharedArtifacts, componentArtifacts) {
     var _a;
     const basePath = (_a = process.env.HANDOFF_APP_BASE_PATH) !== null && _a !== void 0 ? _a : '';
     const clientArtifactUrl = (0, url_1.buildArtifactUrl)(clientArtifactPath(componentId), basePath);
@@ -193,7 +208,7 @@ function generateHtmlDocument(componentId, previewTitle, renderedHtml, props, sh
     <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>`;
 }
@@ -224,7 +239,7 @@ function ssrRenderPlugin(componentData, documentationComponents, handoff) {
         },
         generateBundle(_, bundle) {
             return __awaiter(this, void 0, void 0, function* () {
-                var _a, _b;
+                var _a, _b, _c, _d, _e;
                 // Remove all JS chunks to prevent conflicts
                 for (const [fileName, chunkInfo] of Object.entries(bundle)) {
                     if (chunkInfo.type === 'chunk' && fileName.includes(PLUGIN_CONSTANTS.SCRIPT_ID)) {
@@ -275,15 +290,19 @@ 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, componentData.componentExport);
+                const declarationPath = Object.values((_a = componentData.previews) !== null && _a !== void 0 ? _a : {}).some((preview) => typeof preview.render === 'function')
+                    ? (_b = componentData.entries) === null || _b === void 0 ? void 0 : _b.declaration
+                    : undefined;
+                const clientHydrationSource = generateClientHydrationSource(componentId, componentPath, componentData.componentExport, declarationPath);
                 const clientBuildConfig = Object.assign(Object.assign({}, build_1.DEFAULT_CLIENT_BUILD_CONFIG), { logLevel: 'silent', stdin: {
                         contents: clientHydrationSource,
                         resolveDir: process.cwd(),
                         loader: 'tsx',
                     }, plugins: [(0, build_1.createReactResolvePlugin)(handoff.workingPath, handoff.modulePath)] });
-                const finalClientBuildConfig = ((_b = (_a = handoff.config) === null || _a === void 0 ? void 0 : _a.hooks) === null || _b === void 0 ? void 0 : _b.clientBuildConfig)
+                const hookedClientBuildConfig = ((_d = (_c = handoff.config) === null || _c === void 0 ? void 0 : _c.hooks) === null || _d === void 0 ? void 0 : _d.clientBuildConfig)
                     ? handoff.config.hooks.clientBuildConfig(clientBuildConfig)
                     : clientBuildConfig;
+                const finalClientBuildConfig = (0, build_1.withStyleLoaders)(hookedClientBuildConfig);
                 let clientBundleJs;
                 try {
                     const bundledClient = yield esbuild_1.default.build(finalClientBuildConfig);
@@ -315,11 +334,17 @@ function ssrRenderPlugin(componentData, documentationComponents, handoff) {
                 const componentArtifacts = (0, shared_artifacts_1.resolveComponentArtifactPresence)(handoff, componentId);
                 // Generate previews for each variation
                 for (const previewKey in componentData.previews) {
-                    const previewProps = componentData.previews[previewKey].values;
-                    // Server-side render the component
-                    const serverRenderedHtml = server_1.default.renderToString(react_1.default.createElement(ReactComponent, previewProps));
-                    const formattedHtml = yield (0, html_1.formatHtml)(serverRenderedHtml);
-                    finalHtml = generateHtmlDocument(componentId, componentData.previews[previewKey].title, formattedHtml, previewProps, sharedArtifacts, componentArtifacts);
+                    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 = (_e = preview.sourcePreview) !== null && _e !== void 0 ? _e : 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);
+                    // 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 = server_1.default.renderToString(react_1.default.createElement(PreviewComponent, previewProps));
+                    finalHtml = generateHtmlDocument(componentId, hydrationPreviewKey, preview.title, serverRenderedHtml, previewProps, sharedArtifacts, componentArtifacts);
                     // Emit preview files
                     this.emitFile({
                         type: 'asset',
@@ -340,7 +365,7 @@ function ssrRenderPlugin(componentData, documentationComponents, handoff) {
                         templateFileName: path_1.default.basename(componentPath),
                     });
                 }
-                // Format final HTML and update component data
+                // The previews are already emitted, so this formats only the docs code view.
                 finalHtml = yield (0, html_1.formatHtml)(finalHtml);
                 componentData.format = 'react';
                 componentData.preview = '';

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

@@ -42,6 +42,7 @@ declare const buildComponentCss: (data: TransformComponentTokensResult, handoff:
         story?: string;
         schema?: string;
         templates?: string;
+        declaration?: string;
     };
     renderer?: import("../../../index").RendererKind;
     sourceFormat?: import("../../../index").SourceFormat;

package/dist/transformers/preview/component/css.js

@@ -18,6 +18,7 @@ const path_1 = __importDefault(require("path"));
 const vite_1 = require("vite");
 const duration_1 = require("../../../utils/duration");
 const logger_1 = require("../../../utils/logger");
+const build_1 = require("../../utils/build");
 const vite_config_1 = __importDefault(require("../../vite-config"));
 const component_1 = require("../component");
 const { pathToFileURL } = require('url');
@@ -88,14 +89,49 @@ const buildCssBundle = (_a) => __awaiter(void 0, [_a], void 0, function* ({ entr
         }
     }
 });
+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 = (data, handoff) => __awaiter(void 0, void 0, void 0, function* () {
+    var _a, _b;
+    const template = (_a = data.entries) === null || _a === void 0 ? void 0 : _a.template;
+    const discovered = template ? yield (0, build_1.collectStyleImports)(path_1.default.resolve(template), handoff) : [];
+    const declared = ((_b = data.entries) === null || _b === void 0 ? void 0 : _b.scss) ? [path_1.default.resolve(data.entries.scss)] : [];
+    const ordered = [];
+    const seen = new Set();
+    for (const source of [...discovered, ...declared]) {
+        if (!seen.has(source) && STYLE_SOURCE_EXTENSIONS.has(path_1.default.extname(source)) && fs_extra_1.default.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 = (sources, outputPath, id) => __awaiter(void 0, void 0, void 0, function* () {
+    const entryPath = path_1.default.resolve(outputPath, `.${id}.entry.scss`);
+    const rules = sources.map((source, index) => `@use '${source.split(path_1.default.sep).join('/')}' as ns${index};`);
+    yield fs_extra_1.default.outputFile(entryPath, `${rules.join('\n')}\n`);
+    return entryPath;
+});
 const buildComponentCss = (data, handoff) => __awaiter(void 0, void 0, void 0, function* () {
     var _a, _b, _c;
     const id = data.id;
     logger_1.Logger.debug(`buildComponentCss`, id);
     const outputPath = (0, component_1.getComponentOutputPath)(handoff);
     const builtCssPath = path_1.default.resolve(outputPath, `${id}.css`);
-    const entry = (_a = data.entries) === null || _a === void 0 ? void 0 : _a.scss;
-    if (!entry) {
+    const sources = yield resolveStyleSources(data, handoff);
+    if (sources.length === 0) {
         // Keep generated output aligned with the current component declaration.
         yield fs_extra_1.default.remove(builtCssPath);
         delete data['css'];
@@ -103,59 +139,61 @@ const buildComponentCss = (data, handoff) => __awaiter(void 0, void 0, void 0, f
         delete data['sharedStyles'];
         return data;
     }
-    const extension = path_1.default.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 ? yield writeCombinedStyleEntry(sources, outputPath, id) : undefined;
+    const entry = combinedEntry !== null && combinedEntry !== void 0 ? 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.
-            yield fs_extra_1.default.remove(builtCssPath);
-            // Read the original source
-            const sourceContent = yield fs_extra_1.default.readFile(entry, 'utf8');
-            if (extension === '.scss') {
-                data['sass'] = sourceContent;
-            }
-            // Setup SASS load paths
-            const loadPaths = [
-                path_1.default.resolve(handoff.workingPath),
-                path_1.default.resolve(handoff.workingPath, handoff.exportsDirectory, handoff.getProjectId()),
-                path_1.default.resolve(handoff.workingPath, 'node_modules'),
-            ];
-            if ((_c = (_b = handoff.runtimeConfig) === null || _b === void 0 ? void 0 : _b.entries) === null || _c === void 0 ? void 0 : _c.scss) {
-                loadPaths.unshift(path_1.default.dirname(handoff.runtimeConfig.entries.scss));
-            }
-            yield buildCssBundle({
-                entry,
-                outputPath,
-                outputFilename: `${id}.css`,
-                loadPaths,
-                handoff,
-            });
-            // Read the built CSS
-            if (fs_extra_1.default.existsSync(builtCssPath)) {
-                const builtCss = yield fs_extra_1.default.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];
-                    yield fs_extra_1.default.writeFile(path_1.default.resolve(outputPath, exports.SHARED_COMPONENT_CSS_FILE), data['sharedStyles']);
-                }
-            }
-            else {
-                delete data['css'];
-                delete data['sharedStyles'];
+        // Remove the previous artifact before rebuilding so "no emitted CSS"
+        // doesn't silently preserve stale output from an earlier build.
+        yield fs_extra_1.default.remove(builtCssPath);
+        // Read the original source
+        const primarySource = ((_a = data.entries) === null || _a === void 0 ? void 0 : _a.scss) ? path_1.default.resolve(data.entries.scss) : sources[0];
+        if (path_1.default.extname(primarySource) === '.scss') {
+            data['sass'] = yield fs_extra_1.default.readFile(primarySource, 'utf8');
+        }
+        // Setup SASS load paths
+        const loadPaths = [
+            path_1.default.resolve(handoff.workingPath),
+            path_1.default.resolve(handoff.workingPath, handoff.exportsDirectory, handoff.getProjectId()),
+            path_1.default.resolve(handoff.workingPath, 'node_modules'),
+        ];
+        if ((_c = (_b = handoff.runtimeConfig) === null || _b === void 0 ? void 0 : _b.entries) === null || _c === void 0 ? void 0 : _c.scss) {
+            loadPaths.unshift(path_1.default.dirname(handoff.runtimeConfig.entries.scss));
+        }
+        yield buildCssBundle({
+            entry,
+            outputPath,
+            outputFilename: `${id}.css`,
+            loadPaths,
+            handoff,
+        });
+        // Read the built CSS
+        if (fs_extra_1.default.existsSync(builtCssPath)) {
+            const builtCss = yield fs_extra_1.default.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];
+                yield fs_extra_1.default.writeFile(path_1.default.resolve(outputPath, exports.SHARED_COMPONENT_CSS_FILE), data['sharedStyles']);
             }
         }
+        else {
+            delete data['css'];
+            delete data['sharedStyles'];
+        }
     }
     catch (e) {
         logger_1.Logger.error(`Failed to build CSS for "${id}"`);
         throw e;
     }
+    finally {
+        if (combinedEntry) {
+            yield fs_extra_1.default.remove(combinedEntry);
+        }
+    }
     return data;
 });
 /**

package/dist/transformers/preview/pattern/html.js

@@ -48,7 +48,9 @@ const composePatternHtml = (_patternId, patternTitle, fragments, basePath, share
                 cssHrefs.add((0, url_1.buildArtifactUrl)(`component/${componentId}.css`, basePath));
             }
         }
-        const doc = (0, node_html_parser_1.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 = (0, node_html_parser_1.parse)(html, { comment: true });
         const suffix = `_p${i}`;
         const namespacedRootId = `root${suffix}`;
         const namespacedPropsId = `__APP_PROPS__${suffix}`;

package/dist/transformers/preview/types.d.ts

@@ -14,6 +14,8 @@ export type PageSliceType = 'BEST_PRACTICES' | 'COMPONENT_DISPLAY' | 'VALIDATION
 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';
 }
@@ -22,6 +24,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;
 }
 export interface ValidationResultsPageSlice extends BasePageSlice {
@@ -100,6 +104,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;
     };
@@ -187,6 +193,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. */
@@ -208,6 +216,11 @@ export type OptionalPreviewRender = {
     };
     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/dist/transformers/utils/build.d.ts

@@ -1,4 +1,14 @@
 import esbuild from 'esbuild';
+/**
+ * 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 declare const STYLE_IMPORT_LOADERS: Record<string, esbuild.Loader>;
 /**
  * Default esbuild configuration for SSR builds
  */
@@ -7,6 +17,15 @@ export declare const DEFAULT_SSR_BUILD_CONFIG: esbuild.BuildOptions;
  * Default esbuild configuration for client builds
  */
 export declare const DEFAULT_CLIENT_BUILD_CONFIG: esbuild.BuildOptions;
+/** Apply after a consumer hook: a hook that replaces `loader` would otherwise drop these. */
+export declare function withStyleLoaders<T extends esbuild.BuildOptions>(config: T): T;
+/**
+ * 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 declare function collectStyleImports(entryPath: string, handoff: any): Promise<string[]>;
 /**
  * Resolves a module from multiple search directories
  * @param id - Module ID to resolve