handoff-app 2.0.0-7 → 2.0.0-9

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

package/dist/transformers/utils/build.js

@@ -1,12 +1,35 @@
 "use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DEFAULT_CLIENT_BUILD_CONFIG = exports.DEFAULT_SSR_BUILD_CONFIG = void 0;
+exports.DEFAULT_CLIENT_BUILD_CONFIG = exports.DEFAULT_SSR_BUILD_CONFIG = exports.STYLE_IMPORT_LOADERS = void 0;
+exports.withStyleLoaders = withStyleLoaders;
+exports.collectStyleImports = collectStyleImports;
 exports.resolveModule = resolveModule;
 exports.createReactResolvePlugin = createReactResolvePlugin;
+const esbuild_1 = __importDefault(require("esbuild"));
 const path_1 = __importDefault(require("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.
+ */
+exports.STYLE_IMPORT_LOADERS = Object.fromEntries(STYLE_EXTENSIONS.map((extension) => [extension, 'empty']));
 /**
  * Default esbuild configuration for SSR builds
  */
@@ -17,6 +40,7 @@ exports.DEFAULT_SSR_BUILD_CONFIG = {
     platform: 'node',
     jsx: 'automatic',
     external: ['react', 'react-dom', '@opentelemetry/api'],
+    loader: exports.STYLE_IMPORT_LOADERS,
 };
 /**
  * Default esbuild configuration for client builds
@@ -29,7 +53,65 @@ exports.DEFAULT_CLIENT_BUILD_CONFIG = {
     jsx: 'automatic',
     sourcemap: false,
     minify: false,
+    loader: exports.STYLE_IMPORT_LOADERS,
 };
+/** Apply after a consumer hook: a hook that replaces `loader` would otherwise drop these. */
+function withStyleLoaders(config) {
+    return Object.assign(Object.assign({}, config), { loader: Object.assign(Object.assign({}, config.loader), exports.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, entryPath) {
+    const entryKey = Object.keys(metafile.inputs).find((key) => path_1.default.resolve(key) === entryPath);
+    if (!entryKey)
+        return [];
+    const ordered = [];
+    const visited = new Set();
+    const visit = (key) => {
+        var _a, _b;
+        if (visited.has(key))
+            return;
+        visited.add(key);
+        for (const imported of (_b = (_a = metafile.inputs[key]) === null || _a === void 0 ? void 0 : _a.imports) !== null && _b !== void 0 ? _b : []) {
+            if (!imported.external && metafile.inputs[imported.path])
+                visit(imported.path);
+        }
+        if (STYLE_EXTENSIONS.includes(path_1.default.extname(key)))
+            ordered.push(path_1.default.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.
+ */
+function collectStyleImports(entryPath, handoff) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a, _b;
+        const baseConfig = Object.assign(Object.assign({}, exports.DEFAULT_SSR_BUILD_CONFIG), { entryPoints: [entryPath], logLevel: 'silent' });
+        const hookedConfig = ((_b = (_a = handoff === null || handoff === void 0 ? void 0 : handoff.config) === null || _a === void 0 ? void 0 : _a.hooks) === null || _b === void 0 ? void 0 : _b.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 = yield esbuild_1.default.build(Object.assign(Object.assign({}, withStyleLoaders(hookedConfig)), { metafile: true }));
+            return result.metafile ? orderStyleImports(result.metafile, entryPath) : [];
+        }
+        catch (_c) {
+            return [];
+        }
+    });
+}
 /**
  * Resolves a module from multiple search directories
  * @param id - Module ID to resolve

package/dist/transformers/utils/module.js

@@ -19,9 +19,10 @@ const build_1 = require("./build");
 function createModuleBuildConfig(entryPath, handoff) {
     var _a, _b;
     const defaultBuildConfig = Object.assign(Object.assign({}, build_1.DEFAULT_SSR_BUILD_CONFIG), { entryPoints: [entryPath] });
-    return ((_b = (_a = handoff.config) === null || _a === void 0 ? void 0 : _a.hooks) === null || _b === void 0 ? void 0 : _b.ssrBuildConfig)
+    const hookedBuildConfig = ((_b = (_a = handoff.config) === null || _a === void 0 ? void 0 : _a.hooks) === null || _b === void 0 ? void 0 : _b.ssrBuildConfig)
         ? handoff.config.hooks.ssrBuildConfig(defaultBuildConfig)
         : defaultBuildConfig;
+    return (0, build_1.withStyleLoaders)(hookedBuildConfig);
 }
 function evaluateBuiltModule(code) {
     const mod = { exports: {} };