handoff-app 2.0.0-7 → 2.0.0-9

package/src/registry/connection.ts

@@ -1,22 +1,14 @@
 /**
- * Connected-workspace registry connection resolution.
- *
- * A connected workspace is `runtime.mode: 'workspace'` plus a `runtime.registryConnection` block
- * pointing at a remote registry — it is not a third runtime mode. The connection is resolved from
- * config + environment: the registry URL may be given inline or via an env-var *name*, and the
- * access token is always read from an env-var name (never persisted as a value). This is the single
- * source the publish (and later checkout) client reads its target + credentials from.
- *
- * The older `HANDOFF_CLOUD_*` names still work as deprecated fallbacks; see
- * {@link DEPRECATED_ENV_ALIASES}.
+ * Registry connection values resolve at config load. Saved device login credentials can fill
+ * missing values for CLI operations; neither source is persisted in the app's client config.
  */
 
-import type { Config } from '../types/config';
-import { cliAuthMatchesRegistry, cliAuthTokenIsValid, readCliAuth } from '../cli/auth/store';
+import { configEnvName } from '../config/resolve-env';
+import type { ResolvedConfig } from '../types/config';
+import { type CliAuth, cliAuthMatchesRegistry, cliAuthTokenIsValid, DEFAULT_LOGIN_PROFILE, readCliAuth } from '../cli/auth/store';
 // Imported straight from the module, not the `auth` barrel, to keep the database schema off the CLI
 // startup path; this file is resolved for every command.
 import { resolveRegistrySyncSecret } from './auth/sync-secret';
-import { Logger } from '../utils/logger';
 
 /** Default env-var name holding the remote registry base URL. */
 export const DEFAULT_REGISTRY_URL_ENV = 'HANDOFF_REGISTRY_URL';
@@ -24,38 +16,11 @@ export const DEFAULT_REGISTRY_URL_ENV = 'HANDOFF_REGISTRY_URL';
 /** Default env-var name holding the connected-workspace access token. */
 export const DEFAULT_REGISTRY_ACCESS_TOKEN_ENV = 'HANDOFF_REGISTRY_ACCESS_TOKEN';
 
-/**
- * Old env-var names we still read, keyed by the name that replaced them. Keeps workspaces set up
- * from the older docs working instead of silently reporting no registry.
- */
-const DEPRECATED_ENV_ALIASES: Readonly<Record<string, string>> = {
-  [DEFAULT_REGISTRY_URL_ENV]: 'HANDOFF_CLOUD_URL',
-  [DEFAULT_REGISTRY_ACCESS_TOKEN_ENV]: 'HANDOFF_CLOUD_TOKEN',
-};
-
-/** Aliases we've already warned about, so each one warns once per run and not once per lookup. */
-const warnedAliases = new Set<string>();
-
-/**
- * Value of the named env var, falling back to its deprecated alias. Only the default names have
- * aliases: a custom `urlEnv`/`accessTokenEnv` is a deliberate choice, so a stray `HANDOFF_CLOUD_*`
- * must not stand in for it. The warning goes through {@link Logger.warn}, so
- * `HANDOFF_LOG_LEVEL=error` silences it in CI.
- */
-const readConnectionEnv = (name: string): string => {
-  const configured = process.env[name]?.trim();
-  if (configured) return configured;
-
-  const alias = DEPRECATED_ENV_ALIASES[name];
-  const inherited = alias ? process.env[alias]?.trim() : '';
-  if (!inherited) return '';
-
-  if (!warnedAliases.has(alias)) {
-    warnedAliases.add(alias);
-    Logger.warn(`${alias} is deprecated and will be removed in a future release; set ${name} instead.`);
-  }
-  return inherited;
-};
+/** A saved login and the profile it is stored under, which is not always the selected profile. */
+interface SavedLogin {
+  profile: string;
+  url: string;
+}
 
 /** Fully resolved connected-workspace registry connection. */
 export interface ResolvedRegistryConnection {
@@ -67,55 +32,91 @@ export interface ResolvedRegistryConnection {
   urlEnv: string;
   /** Name of the env var the access token is read from. */
   accessTokenEnv: string;
+  /** Profile the saved login was looked up under. */
+  loginProfile: string;
+  /** Set when a saved login was skipped because it was issued for another registry. */
+  unmatchedLogin?: SavedLogin;
 }
 
-/**
- * Resolve the connected-workspace registry connection from config + environment. Never throws —
- * Callers inspect the resolved URL and access token to surface specific configuration errors.
- *
- * `urlEnv` and `accessTokenEnv` always report the canonical name, even when an alias supplied the
- * value, so errors built from them point at the variable to adopt.
- */
-export const resolveRegistryConnection = (config: Config | null | undefined): ResolvedRegistryConnection => {
+/** Read values resolved at config load, retaining variable names for CLI diagnostics. */
+export const resolveRegistryConnection = (config: ResolvedConfig | null | undefined): ResolvedRegistryConnection => {
   const connection = config?.runtime?.registryConnection;
-  const urlEnv = connection?.urlEnv?.trim() || DEFAULT_REGISTRY_URL_ENV;
-  const accessTokenEnv = connection?.accessTokenEnv?.trim() || DEFAULT_REGISTRY_ACCESS_TOKEN_ENV;
-
-  const inlineUrl = connection?.url?.trim();
-  const url = inlineUrl || readConnectionEnv(urlEnv);
-  const accessToken = readConnectionEnv(accessTokenEnv);
+  const urlEnv = configEnvName(config, 'runtime.registryConnection.url') || DEFAULT_REGISTRY_URL_ENV;
+  const accessTokenEnv = configEnvName(config, 'runtime.registryConnection.accessToken') || DEFAULT_REGISTRY_ACCESS_TOKEN_ENV;
+  const url = connection?.url?.trim() || '';
+  const accessToken = connection?.accessToken?.trim() || '';
 
   return {
     url,
     accessToken,
     urlEnv,
     accessTokenEnv,
+    loginProfile: DEFAULT_LOGIN_PROFILE,
   };
 };
 
+/**
+ * The valid login to use for a profile. A profile without its own login falls back to the default
+ * login, so a workspace that names profiles for other reasons keeps working after one plain
+ * `handoff-app login`. The fallback is safe because a token is only ever used for the registry URL
+ * it was issued for.
+ */
+const readProfileLogin = async (workingPath: string, profile: string): Promise<{ auth: CliAuth; profile: string } | null> => {
+  const own = await readCliAuth(workingPath, profile);
+  if (cliAuthTokenIsValid(own)) return { auth: own!, profile };
+
+  const fallback = profile === DEFAULT_LOGIN_PROFILE ? null : await readCliAuth(workingPath);
+  return cliAuthTokenIsValid(fallback) ? { auth: fallback!, profile: DEFAULT_LOGIN_PROFILE } : null;
+};
+
 /**
  * Resolve the same connection for an authenticated CLI operation, letting a saved device login fill
  * in what the environment does not provide. A valid login supplies both the registry URL and the
- * access token, so `handoff-app login` alone is enough to publish and checkout. Environment values
- * keep precedence for deterministic CI: `HANDOFF_REGISTRY_URL` (or inline config) wins over the
- * saved URL, and `HANDOFF_REGISTRY_ACCESS_TOKEN` wins over the saved token. The saved token only
- * applies to the URL it was issued for.
+ * access token, so `handoff-app login` alone is enough to publish and checkout. The login is the one
+ * saved under the selected profile, which is how one workspace addresses several registries.
+ * Environment values keep precedence for deterministic CI: `HANDOFF_REGISTRY_URL` (or inline config)
+ * wins over the saved URL, and `HANDOFF_REGISTRY_ACCESS_TOKEN` wins over the saved token. The saved
+ * token only applies to the URL it was issued for.
  *
  * A configured `HANDOFF_SYNC_SECRET` is the last resort. Being deployment-wide rather than personal,
  * it fills in only where there is no explicit token and no login (CI, in practice), instead of quietly
  * speaking for a developer who is signed in.
  */
 export const resolveAuthenticatedRegistryConnection = async (
-  config: Config | null | undefined,
-  workingPath = process.cwd()
+  config: ResolvedConfig | null | undefined,
+  workingPath = process.cwd(),
+  profile?: string
 ): Promise<ResolvedRegistryConnection> => {
   const connection = resolveRegistryConnection(config);
+  const loginProfile = profile?.trim() || DEFAULT_LOGIN_PROFILE;
 
-  const auth = await readCliAuth(workingPath);
-  const login = cliAuthTokenIsValid(auth) ? auth! : null;
+  const login = await readProfileLogin(workingPath, loginProfile);
+  const url = connection.url || login?.auth.remoteUrl || '';
+  const matches = Boolean(login) && cliAuthMatchesRegistry(login!.auth, url);
+  const accessToken = connection.accessToken || (matches ? login!.auth.accessToken : '') || resolveRegistrySyncSecret();
 
-  const url = connection.url || login?.remoteUrl || '';
-  const savedToken = login && cliAuthMatchesRegistry(login, url) ? login.accessToken : '';
-  const accessToken = connection.accessToken || savedToken || resolveRegistrySyncSecret();
-  return { ...connection, url, accessToken };
+  return {
+    ...connection,
+    url,
+    accessToken,
+    loginProfile,
+    unmatchedLogin: login && !matches ? { profile: login.profile, url: login.auth.remoteUrl } : undefined,
+  };
 };
+
+/** The `handoff-app login` call that would authorize this connection, naming the selected profile. */
+export const loginCommandHint = (connection: ResolvedRegistryConnection): string =>
+  [
+    'handoff-app login',
+    connection.loginProfile === DEFAULT_LOGIN_PROFILE ? '' : ` --profile ${connection.loginProfile}`,
+    ` --url ${connection.url || '<registry-url>'}`,
+  ].join('');
+
+/**
+ * Names a saved login that was skipped because it belongs to another registry. Without it, a run
+ * that resolves its URL from the environment reports a missing token while a login is in place.
+ */
+export const unusedLoginNote = (connection: ResolvedRegistryConnection): string =>
+  connection.unmatchedLogin
+    ? ` The login saved for profile "${connection.unmatchedLogin.profile}" is for ${connection.unmatchedLogin.url}, not ${connection.url}.`
+    : '';

package/src/registry/db/driver.ts

@@ -10,7 +10,7 @@
  * the value is never stored in config.
  */
 
-import type { Config } from '../../types/config';
+import type { ResolvedConfig } from '../../types/config';
 
 /** Built-in registry database connection driver. Both ship with the package and target Postgres. */
 export type RegistryDatabaseDriver = 'pg' | 'neon';
@@ -35,24 +35,13 @@ export interface ResolvedRegistryDatabase {
 }
 
 /** Resolve the env-var name holding the database URL (defaults to `DATABASE_URL`). */
-export const resolveDatabaseUrlEnv = (config: Config | null | undefined): string => {
-  const configured = config?.runtime?.registry?.databaseUrlEnv?.trim();
+export const resolveDatabaseUrlEnv = (config: ResolvedConfig | null | undefined): string => {
+  const configured = config?.runtime?.registry?.databaseUrl?.$env?.trim();
   return configured || DEFAULT_DATABASE_URL_ENV;
 };
 
-/**
- * Resolve the legacy fixed-token env-var name for configuration compatibility.
- *
- * @deprecated The returned env var is intentionally ignored by registry authorization. Use a
- * user-issued access token or `handoff-app login`.
- */
-export const resolveApiTokenEnv = (config: Config | null | undefined): string => {
-  const configured = config?.runtime?.registry?.apiTokenEnv?.trim();
-  return configured || DEFAULT_REGISTRY_API_TOKEN_ENV;
-};
-
 /** Resolve the configured registry database driver (defaults to `pg`). */
-export const resolveRegistryDriver = (config: Config | null | undefined): RegistryDatabaseDriver => {
+export const resolveRegistryDriver = (config: ResolvedConfig | null | undefined): RegistryDatabaseDriver => {
   return config?.runtime?.registry?.database?.driver ?? DEFAULT_REGISTRY_DRIVER;
 };
 
@@ -61,7 +50,7 @@ export const resolveRegistryDriver = (config: Config | null | undefined): Regist
  * when the configured env var is unset so the CLI can surface a clear "missing database URL"
  * message instead of failing deep inside the driver.
  */
-export const resolveRegistryDatabase = (config: Config | null | undefined): ResolvedRegistryDatabase => {
+export const resolveRegistryDatabase = (config: ResolvedConfig | null | undefined): ResolvedRegistryDatabase => {
   const driver = resolveRegistryDriver(config);
   const databaseUrlEnv = resolveDatabaseUrlEnv(config);
   const connectionString = process.env[databaseUrlEnv]?.trim();
@@ -69,7 +58,7 @@ export const resolveRegistryDatabase = (config: Config | null | undefined): Reso
   if (!connectionString) {
     throw new Error(
       `Registry database URL is not configured. Set the "${databaseUrlEnv}" environment variable to a ` +
-        `PostgreSQL connection string (or change "runtime.registry.databaseUrlEnv" to point at the env var you use).`
+        `PostgreSQL connection string (or change "runtime.registry.databaseUrl" to point at the env var you use).`
     );
   }
 

package/src/registry/db/index.ts

@@ -29,7 +29,6 @@ export {
   DEFAULT_DATABASE_URL_ENV,
   DEFAULT_REGISTRY_DRIVER,
   DEFAULT_REGISTRY_API_TOKEN_ENV,
-  resolveApiTokenEnv,
   resolveDatabaseUrlEnv,
   resolveRegistryDriver,
   resolveRegistryDatabase,

package/src/registry/publish/index.ts

@@ -17,7 +17,7 @@ import processComponents from '../../transformers/preview/component/builder';
 import { processPatterns } from '../../transformers/preview/pattern/builder';
 import { Logger } from '../../utils/logger';
 import { createRegistryClient, RegistryClientError, type RegistryClient } from '../client';
-import { resolveAuthenticatedRegistryConnection } from '../connection';
+import { loginCommandHint, resolveAuthenticatedRegistryConnection, unusedLoginNote } from '../connection';
 import type { EntitySummary, TransferEntityKind } from '../transfer';
 import { quoteIds, selectIds, splitCatalogIds } from '../selection';
 import { describePublishError, describeUploadFailure } from './errors';
@@ -74,17 +74,17 @@ const assertUniqueCatalogIds = (handoff: Handoff): void => {
 export const resolveConnectionOrThrow = async (handoff: Handoff) => {
   assertPublishableWorkspace(handoff);
 
-  const connection = await resolveAuthenticatedRegistryConnection(handoff.config, handoff.workingPath);
+  const connection = await resolveAuthenticatedRegistryConnection(handoff.config, handoff.workingPath, handoff.getProfile());
   if (!connection.url) {
     throw new PublishError(
-      `No registry is configured. Run \`handoff-app login --url <registry-url>\`, set runtime.registryConnection.url, ` +
+      `No registry is configured. Run \`${loginCommandHint(connection)}\`, set runtime.registryConnection.url, ` +
         `or set the "${connection.urlEnv}" environment variable to the base URL of the registry to publish to.`
     );
   }
   if (!connection.accessToken) {
     throw new PublishError(
-      `No registry access token is configured. Run \`handoff-app login --url ${connection.url}\`, or set the ` +
-        `"${connection.accessTokenEnv}" environment variable to a user-issued token for CI.`
+      `No registry access token is configured. Run \`${loginCommandHint(connection)}\`, or set the ` +
+        `"${connection.accessTokenEnv}" environment variable to a user-issued token for CI.${unusedLoginNote(connection)}`
     );
   }
   return connection;

package/src/store/filesystem.ts

@@ -14,7 +14,7 @@ import path from 'path';
 import { resolveTokenTransformers, tokenArtifactPathsForSet } from '../pipeline/token-transformers';
 import { deriveTokenSets, isComponentSet, setNameForId } from '../registry/tokens/sets';
 import type { ComponentListObject, PageListObject, PatternListObject } from '../transformers/preview/types';
-import type { Config, RuntimeConfig } from '../types/config';
+import type { ResolvedConfig, RuntimeConfig } from '../types/config';
 import { getRelatedSourceFilesForRecord, sourceContentTypeForPath } from './source-files';
 import type {
   ComponentStore,
@@ -34,7 +34,7 @@ import type {
  */
 export interface FilesystemStoreContext {
   runtimeConfig?: RuntimeConfig | null;
-  config?: Config | null;
+  config?: ResolvedConfig | null;
   /** Workspace root (`Handoff.workingPath`), holding `public/` and `fonts/`. */
   workingPath?: string;
   /** Absolute path to the generated `tokens.json` (`Handoff.getTokensFilePath()`). */

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}`;