handoff-app 2.0.0-8 → 2.0.0

package/dist/registry/email/types.js

@@ -0,0 +1,6 @@
+"use strict";
+/**
+ * Server-only email provider contract. Handoff renders every message, and a provider only delivers it.
+ * SMTP is built in. Anything else is a {@link defineEmailProvider} module.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/registry/path.d.ts

@@ -1,4 +1,6 @@
 export declare const isSafeRelativePath: (value: string) => boolean;
 export declare const normalizeRelativePath: (value: string) => string;
+/** Unlike {@link isSafeRelativePath}, it can start with `../`. */
+export declare const isWorkspaceRelativePath: (value: unknown) => value is string;
 export declare const isSafePathSegment: (value: string) => boolean;
 export declare const resolvePathWithin: (root: string, value: string) => string | null;

package/dist/registry/path.js

@@ -3,7 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.resolvePathWithin = exports.isSafePathSegment = exports.normalizeRelativePath = exports.isSafeRelativePath = void 0;
+exports.resolvePathWithin = exports.isSafePathSegment = exports.isWorkspaceRelativePath = exports.normalizeRelativePath = exports.isSafeRelativePath = void 0;
 const path_1 = __importDefault(require("path"));
 const isSafeRelativePath = (value) => {
     if (typeof value !== 'string' || value.trim() === '') {
@@ -18,6 +18,16 @@ const isSafeRelativePath = (value) => {
 exports.isSafeRelativePath = isSafeRelativePath;
 const normalizeRelativePath = (value) => value.replace(/\\/g, '/');
 exports.normalizeRelativePath = normalizeRelativePath;
+/** Unlike {@link isSafeRelativePath}, it can start with `../`. */
+const isWorkspaceRelativePath = (value) => typeof value === 'string' &&
+    value !== '' &&
+    value !== '.' &&
+    !value.includes('\0') &&
+    !value.includes('\\') &&
+    !value.startsWith('/') &&
+    !/^[a-zA-Z]:/.test(value) &&
+    path_1.default.posix.normalize(value) === value;
+exports.isWorkspaceRelativePath = isWorkspaceRelativePath;
 const isSafePathSegment = (value) => typeof value === 'string' && value === value.trim() && (0, exports.isSafeRelativePath)(value) && !(0, exports.normalizeRelativePath)(value).includes('/');
 exports.isSafePathSegment = isSafePathSegment;
 const resolvePathWithin = (root, value) => {

package/dist/registry/publish/package.js

@@ -97,6 +97,12 @@ const enrichItem = (handoff, kind, id, summary) => __awaiter(void 0, void 0, voi
     }
     return item;
 });
+const findSourceDir = (handoff, kind, id) => __awaiter(void 0, void 0, void 0, function* () {
+    const runtime = kind === 'component' ? yield handoff.store.components.get(id) : yield handoff.store.patterns.get(id);
+    const sourceDir = runtime === null || runtime === void 0 ? void 0 : runtime.path;
+    const relativeDir = sourceDir ? path_1.default.relative(handoff.workingPath, sourceDir) : '';
+    return relativeDir && !path_1.default.isAbsolute(relativeDir) ? relativeDir.split(path_1.default.sep).join('/') : undefined;
+});
 /** Map an entity's related source files to transfer files, dropping workspace-only declarations. */
 const collectSourceFiles = (handoff, kind, id) => __awaiter(void 0, void 0, void 0, function* () {
     const store = kind === 'component' ? handoff.store.components : kind === 'pattern' ? handoff.store.patterns : handoff.store.pages;
@@ -164,6 +170,7 @@ const buildComponentPackage = (handoff, id) => __awaiter(void 0, void 0, void 0,
     const artifacts = Array.from(byPath.values());
     return {
         item: yield enrichItem(handoff, 'component', id, summary),
+        sourceDir: yield findSourceDir(handoff, 'component', id),
         files: yield collectSourceFiles(handoff, 'component', id),
         artifacts,
         build: createArtifactBuild(artifacts),
@@ -206,6 +213,7 @@ const buildPatternPackage = (handoff, id) => __awaiter(void 0, void 0, void 0, f
     const artifacts = Array.from(byPath.values());
     return {
         item: yield enrichItem(handoff, 'pattern', id, summary),
+        sourceDir: yield findSourceDir(handoff, 'pattern', id),
         files: yield collectSourceFiles(handoff, 'pattern', id),
         artifacts,
         build: createArtifactBuild(artifacts),

package/dist/registry/transfer.d.ts

@@ -59,6 +59,8 @@ export interface TransferBuild {
 export interface TransferPackage {
     /** Normalized component, pattern, or page record stored as the served record. */
     item: Record<string, unknown>;
+    /** Workspace-relative entity directory, for components and patterns. It can start with `../`. */
+    sourceDir?: string;
     files: TransferFile[];
     artifacts: TransferArtifact[];
     build: TransferBuild;
@@ -71,6 +73,8 @@ export interface CheckoutPayload {
     kind: TransferEntityKind;
     /** Normalized record used to reconstruct the entity. */
     item: Record<string, unknown>;
+    /** The published {@link TransferPackage.sourceDir}. */
+    sourceDir?: string;
     files: TransferFile[];
 }
 /**

package/dist/store/registry.d.ts

@@ -13,7 +13,7 @@
  * - Reads never materialize source files or run the build pipeline — every record and file is
  *   returned exactly as it was published.
  */
-import type { AssetStorage } from '../registry/asset-storage/types';
+import type { StorageProvider } from '../registry/asset-storage/types';
 import type { RegistryDatabase } from '../registry/db/client';
 import { type AssetStorageProvider } from '../registry/db/schema';
 import type { ComponentListObject, PageListObject, PatternListObject } from '../transformers/preview/types';
@@ -22,11 +22,11 @@ import type { AssetContentResource, AssetMetadata, AssetStore, ComponentStore, H
 export interface RegistryStoreContext {
     db: RegistryDatabase;
     /**
-     * Resolve the {@link AssetStorage} adapter for a blob's recorded provider (or `null` for the inline
+     * Resolve the {@link StorageProvider} for a blob's recorded provider (or `null` for the inline
      * `database` provider). Injected by the app runtime so `src/store` stays free of app-side imports;
      * when omitted, only inline DB-backed asset content is resolvable.
      */
-    resolveAssetAdapter?: (provider: AssetStorageProvider) => Promise<AssetStorage | null>;
+    resolveStorageProvider?: (provider: AssetStorageProvider) => Promise<StorageProvider | null>;
 }
 export declare class RegistryComponentStore implements ComponentStore {
     private readonly context;

package/dist/store/registry.js

@@ -404,14 +404,14 @@ class RegistryAssetStore {
                 return Object.assign(Object.assign({}, base), { body: Buffer.from(row.blobContent) });
             }
             // Object-backed - resolve through the provider that stored it.
-            if (!row.storageRef || !this.context.resolveAssetAdapter) {
+            if (!row.storageRef || !this.context.resolveStorageProvider) {
                 return null;
             }
-            const adapter = yield this.context.resolveAssetAdapter(row.storageProvider);
-            if (!adapter) {
+            const storage = yield this.context.resolveStorageProvider(row.storageProvider);
+            if (!storage) {
                 return null;
             }
-            const result = yield adapter.get(row.storageRef);
+            const result = yield storage.get(row.storageRef);
             if (result.kind === 'redirect') {
                 return Object.assign(Object.assign({}, base), { redirectUrl: result.url });
             }

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/builder.d.ts

@@ -9,20 +9,12 @@ export declare enum ComponentSegment {
     Previews = "previews",
     Validation = "validation"
 }
-/**
- * Options for processing components
- */
-export interface ProcessComponentsOptions {
-    /** Enable caching to skip unchanged components */
-    useCache?: boolean;
-}
 /**
  * Process components and generate their code, styles, and previews
  * @param handoff - The Handoff instance containing configuration and state
  * @param id - Optional component ID to process a specific component
  * @param segmentToProcess - Optional segment to update
- * @param options - Optional processing options including cache settings
  * @returns Promise resolving to an array of processed components
  */
-export declare function processComponents(handoff: Handoff, id?: string, segmentToProcess?: ComponentSegment, options?: ProcessComponentsOptions): Promise<ComponentListObject[]>;
+export declare function processComponents(handoff: Handoff, id?: string, segmentToProcess?: ComponentSegment): Promise<ComponentListObject[]>;
 export default processComponents;

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

@@ -153,12 +153,11 @@ const createComponentBuildPlan = (segmentToProcess, existingData) => {
  * @param handoff - The Handoff instance containing configuration and state
  * @param id - Optional component ID to process a specific component
  * @param segmentToProcess - Optional segment to update
- * @param options - Optional processing options including cache settings
  * @returns Promise resolving to an array of processed components
  */
-function processComponents(handoff, id, segmentToProcess, options) {
+function processComponents(handoff, id, segmentToProcess) {
     return __awaiter(this, void 0, void 0, function* () {
-        var _a, _b, _c, _d;
+        var _a, _b, _c, _d, _e;
         const result = [];
         const documentationObject = yield handoff.getDocumentationObject();
         const components = (_a = documentationObject === null || documentationObject === void 0 ? void 0 : documentationObject.components) !== null && _a !== void 0 ? _a : {};
@@ -177,17 +176,16 @@ function processComponents(handoff, id, segmentToProcess, options) {
             yield (0, artifacts_1.syncComponentArtifacts)(handoff, [id]);
             return [];
         }
-        // Determine which components need building based on cache (when enabled)
+        // Determine which components need building based on cache
         let componentsToBuild;
         let cache = null;
         let currentGlobalDeps = {};
         const componentFileStatesMap = new Map();
         // Only use caching when:
-        // - useCache option is enabled
         // - No specific component ID is requested (full build scenario)
         // - No specific segment is requested (full build scenario)
         // - Force flag is not set
-        const shouldUseCache = (options === null || options === void 0 ? void 0 : options.useCache) && !id && !segmentToProcess && !handoff.force;
+        const shouldUseCache = !id && !segmentToProcess && !handoff.force;
         if (shouldUseCache) {
             logger_1.Logger.debug('Loading build cache...');
             cache = yield (0, cache_1.loadBuildCache)(handoff);
@@ -209,7 +207,7 @@ function processComponents(handoff, id, segmentToProcess, options) {
                         logger_1.Logger.info(`Component '${componentId}': new component, will build`);
                         componentsToBuild.add(componentId);
                     }
-                    else if ((0, cache_1.hasComponentChanged)(cachedEntry, currentFileStates)) {
+                    else if (yield (0, cache_1.hasComponentChanged)(cachedEntry, currentFileStates)) {
                         logger_1.Logger.info(`Component '${componentId}': source files changed, will rebuild`);
                         componentsToBuild.add(componentId);
                     }
@@ -329,6 +327,7 @@ function processComponents(handoff, id, segmentToProcess, options) {
             }
             // Components should always have at least one preview variation.
             ensureDefaultPreview(data);
+            const inputs = shouldUseCache ? (0, cache_1.createBuildInputs)() : undefined;
             const runsViteBuildSteps = buildPlan.js || buildPlan.css || buildPlan.previews;
             let viteBuildStartedAtMs = 0;
             if (runsViteBuildSteps) {
@@ -337,15 +336,15 @@ function processComponents(handoff, id, segmentToProcess, options) {
             }
             // Build JS if needed (new build, validation missing, or explicit segment request).
             if (buildPlan.js) {
-                data = yield (0, javascript_1.default)(data, handoff);
+                data = yield (0, javascript_1.default)(data, handoff, inputs);
             }
             // Build CSS if needed.
             if (buildPlan.css) {
-                data = yield (0, css_1.default)(data, handoff);
+                data = yield (0, css_1.default)(data, handoff, inputs);
             }
             // Build previews (HTML, snapshots, etc) if needed.
             if (buildPlan.previews) {
-                data = yield (0, html_1.default)(Object.assign(Object.assign({}, data), { previews: getBuildPreviews(data) }), handoff, components);
+                data = yield (0, html_1.default)(Object.assign(Object.assign({}, data), { previews: getBuildPreviews(data) }), handoff, components, inputs);
             }
             if (runsViteBuildSteps) {
                 const elapsedMs = Date.now() - viteBuildStartedAtMs;
@@ -371,18 +370,19 @@ function processComponents(handoff, id, segmentToProcess, options) {
             // Add to the cumulative results, to later update the global components summary file.
             result.push(summary);
             // Update cache entry for this component after successful build
-            if (shouldUseCache) {
+            if (shouldUseCache && inputs) {
                 if (!cache) {
                     cache = (0, cache_1.createEmptyCache)();
                 }
-                const fileStates = componentFileStatesMap.get(runtimeComponentId);
-                if (fileStates) {
-                    (0, cache_1.updateComponentCacheEntry)(cache, runtimeComponentId, fileStates);
+                // Compute file states if not already computed (e.g., when global deps changed)
+                const fileStates = (_e = componentFileStatesMap.get(runtimeComponentId)) !== null && _e !== void 0 ? _e : (yield (0, cache_1.computeComponentFileStates)(handoff, runtimeComponentId));
+                const inputStates = yield (0, cache_1.computeBuildInputStates)(handoff, runtimeComponentId, inputs);
+                if (inputStates) {
+                    (0, cache_1.updateComponentCacheEntry)(cache, runtimeComponentId, fileStates, inputStates);
                 }
                 else {
-                    // Compute file states if not already computed (e.g., when global deps changed)
-                    const computedFileStates = yield (0, cache_1.computeComponentFileStates)(handoff, runtimeComponentId);
-                    (0, cache_1.updateComponentCacheEntry)(cache, runtimeComponentId, computedFileStates);
+                    // An incomplete list can miss a changed file, so the next run builds this component again.
+                    delete cache.components[runtimeComponentId];
                 }
             }
         }

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

@@ -1,8 +1,9 @@
+import { BuildInputs } from '../../../cache/build-inputs';
 import Handoff from '../../../index';
 import { TransformComponentTokensResult } from '../types';
 export declare const MAIN_COMPONENT_CSS_FILE = "main.css";
 export declare const SHARED_COMPONENT_CSS_FILE = "shared.css";
-declare const buildComponentCss: (data: TransformComponentTokensResult, handoff: Handoff) => Promise<{
+declare const buildComponentCss: (data: TransformComponentTokensResult, handoff: Handoff, inputs?: BuildInputs) => Promise<{
     id: string;
     type?: import("../types").ComponentType;
     image?: string;
@@ -42,6 +43,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

@@ -16,8 +16,10 @@ exports.buildMainCss = exports.SHARED_COMPONENT_CSS_FILE = exports.MAIN_COMPONEN
 const fs_extra_1 = __importDefault(require("fs-extra"));
 const path_1 = __importDefault(require("path"));
 const vite_1 = require("vite");
+const build_inputs_1 = require("../../../cache/build-inputs");
 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');
@@ -32,8 +34,9 @@ exports.SHARED_COMPONENT_CSS_FILE = 'shared.css';
  * @param options.outputFilename - The name of the output file
  * @param options.loadPaths - Array of paths for SASS to look for imports
  * @param options.handoff - The Handoff configuration object
+ * @param options.inputs - Collects the files that the build reads, for the build cache
  */
-const buildCssBundle = (_a) => __awaiter(void 0, [_a], void 0, function* ({ entry, outputPath, outputFilename, loadPaths, handoff, }) {
+const buildCssBundle = (_a) => __awaiter(void 0, [_a], void 0, function* ({ entry, outputPath, outputFilename, loadPaths, handoff, inputs, }) {
     var _b, _c;
     // Store the current NODE_ENV value
     const oldNodeEnv = process.env.NODE_ENV;
@@ -72,7 +75,7 @@ const buildCssBundle = (_a) => __awaiter(void 0, [_a], void 0, function* ({ entr
         if ((_c = (_b = handoff === null || handoff === void 0 ? void 0 : handoff.config) === null || _b === void 0 ? void 0 : _b.hooks) === null || _c === void 0 ? void 0 : _c.cssBuildConfig) {
             viteConfig = handoff.config.hooks.cssBuildConfig(viteConfig);
         }
-        yield (0, vite_1.build)(viteConfig);
+        yield (0, vite_1.build)((0, build_inputs_1.withBuildInputs)(viteConfig, inputs));
     }
     catch (e) {
         logger_1.Logger.error(`Failed to build CSS for "${entry}"`);
@@ -88,14 +91,49 @@ const buildCssBundle = (_a) => __awaiter(void 0, [_a], void 0, function* ({ entr
         }
     }
 });
-const buildComponentCss = (data, handoff) => __awaiter(void 0, void 0, void 0, function* () {
+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, inputs) => __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 +141,62 @@ 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),
+            handoff.getOutputPath(),
+            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,
+            inputs,
+        });
+        // 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;
 });
 /**
@@ -179,7 +220,7 @@ const buildMainCss = (handoff) => __awaiter(void 0, void 0, void 0, function* ()
                 const loadPaths = [
                     path_1.default.dirname(scssEntry),
                     path_1.default.resolve(handoff.workingPath),
-                    path_1.default.resolve(handoff.workingPath, handoff.exportsDirectory, handoff.getProjectId()),
+                    handoff.getOutputPath(),
                     path_1.default.resolve(handoff.workingPath, 'node_modules'),
                 ];
                 yield buildCssBundle({

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

@@ -1,4 +1,5 @@
 import { Types as CoreTypes } from 'handoff-core';
+import { BuildInputs } from '../../../cache/build-inputs';
 import Handoff from '../../../index';
 import { TransformComponentTokensResult } from '../types';
 /**
@@ -7,6 +8,7 @@ import { TransformComponentTokensResult } from '../types';
  * @param data - The result of transforming component tokens.
  * @param handoff - The Handoff configuration object.
  * @param components - Optional file components object.
+ * @param inputs - Collects the files that the build reads, for the build cache.
  * @returns A promise that resolves to the transformed component tokens result.
  * @throws Will throw an error if the Vite build process fails.
  *
@@ -15,5 +17,5 @@ import { TransformComponentTokensResult } from '../types';
  * const result = await buildPreviews(transformedData, handoffConfig, fileComponents);
  * ```
  */
-export declare const buildPreviews: (data: TransformComponentTokensResult, handoff: Handoff, components?: CoreTypes.IDocumentationObject["components"]) => Promise<TransformComponentTokensResult>;
+export declare const buildPreviews: (data: TransformComponentTokensResult, handoff: Handoff, components?: CoreTypes.IDocumentationObject["components"], inputs?: BuildInputs) => Promise<TransformComponentTokensResult>;
 export default buildPreviews;