handoff-app 2.0.0-8 → 2.0.0

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

@@ -15,6 +15,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.buildPreviews = void 0;
 const plugin_react_1 = __importDefault(require("@vitejs/plugin-react"));
 const vite_1 = require("vite");
+const build_inputs_1 = require("../../../cache/build-inputs");
 const logger_1 = require("../../../utils/logger");
 const plugins_1 = require("../../plugins");
 const vite_config_1 = __importDefault(require("../../vite-config"));
@@ -37,6 +38,7 @@ const RENDERER_PLUGINS = {
  * @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.
  *
@@ -45,7 +47,7 @@ const RENDERER_PLUGINS = {
  * const result = await buildPreviews(transformedData, handoffConfig, fileComponents);
  * ```
  */
-const buildPreviews = (data, handoff, components) => __awaiter(void 0, void 0, void 0, function* () {
+const buildPreviews = (data, handoff, components, inputs) => __awaiter(void 0, void 0, void 0, function* () {
     var _a, _b, _c;
     if (!((_a = data.entries) === null || _a === void 0 ? void 0 : _a.template))
         return data;
@@ -75,9 +77,11 @@ const buildPreviews = (data, handoff, components) => __awaiter(void 0, void 0, v
         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.htmlBuildConfig) {
             viteConfig = handoff.config.hooks.htmlBuildConfig(viteConfig);
         }
-        yield (0, vite_1.build)(viteConfig);
+        yield (0, vite_1.build)((0, build_inputs_1.withBuildInputs)(viteConfig, inputs));
     }
     catch (error) {
+        if (inputs)
+            inputs.failed = true;
         logger_1.Logger.error(`Error building component previews: ${data.entries.template}`, error);
     }
     finally {

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

@@ -1,3 +1,4 @@
+import { BuildInputs } from '../../../cache/build-inputs';
 import Handoff from '../../../index';
 import { TransformComponentTokensResult } from '../types';
 export declare const MAIN_COMPONENT_JS_FILE = "main.js";
@@ -10,7 +11,7 @@ export declare const MAIN_COMPONENT_JS_FILE = "main.js";
  * @param handoff - The Handoff configuration object
  * @returns The updated component transformation result with JavaScript data
  */
-export declare const buildComponentJs: (data: TransformComponentTokensResult, handoff: Handoff) => Promise<TransformComponentTokensResult>;
+export declare const buildComponentJs: (data: TransformComponentTokensResult, handoff: Handoff, inputs?: BuildInputs) => Promise<TransformComponentTokensResult>;
 /**
  * Builds the global preview script artifact (`component/main.js`) from the configured workspace JS
  * entry.

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

@@ -16,6 +16,7 @@ exports.buildMainJS = exports.buildComponentJs = exports.MAIN_COMPONENT_JS_FILE
 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 vite_config_1 = __importDefault(require("../../vite-config"));
@@ -28,8 +29,9 @@ exports.MAIN_COMPONENT_JS_FILE = 'main.js';
  * @param options.entry - The entry file path for the bundle
  * @param options.outputPath - The directory where the bundle will be output
  * @param options.outputFilename - The name of the output file
+ * @param inputs - Collects the files that the build reads, for the build cache
  */
-const buildJsBundle = (_a, handoff_1) => __awaiter(void 0, [_a, handoff_1], void 0, function* ({ entry, outputPath, outputFilename, format = 'cjs', }, handoff) {
+const buildJsBundle = (_a, handoff_1, inputs_1) => __awaiter(void 0, [_a, handoff_1, inputs_1], void 0, function* ({ entry, outputPath, outputFilename, format = 'cjs', }, handoff, inputs) {
     var _b, _c, _d;
     const absEntryPath = path_1.default.resolve(entry);
     // Store the current NODE_ENV value before vite build
@@ -51,7 +53,7 @@ const buildJsBundle = (_a, handoff_1) => __awaiter(void 0, [_a, handoff_1], void
         if ((_d = (_c = handoff === null || handoff === void 0 ? void 0 : handoff.config) === null || _c === void 0 ? void 0 : _c.hooks) === null || _d === void 0 ? void 0 : _d.jsBuildConfig) {
             viteConfig = handoff.config.hooks.jsBuildConfig(viteConfig);
         }
-        yield (0, vite_1.build)(viteConfig);
+        yield (0, vite_1.build)((0, build_inputs_1.withBuildInputs)(viteConfig, inputs));
     }
     finally {
         // Restore the original NODE_ENV value after vite build completes
@@ -74,7 +76,7 @@ const buildJsBundle = (_a, handoff_1) => __awaiter(void 0, [_a, handoff_1], void
  * @param handoff - The Handoff configuration object
  * @returns The updated component transformation result with JavaScript data
  */
-const buildComponentJs = (data, handoff) => __awaiter(void 0, void 0, void 0, function* () {
+const buildComponentJs = (data, handoff, inputs) => __awaiter(void 0, void 0, void 0, function* () {
     var _a;
     const id = data.id;
     const outputPath = (0, component_1.getComponentOutputPath)(handoff);
@@ -97,9 +99,11 @@ const buildComponentJs = (data, handoff) => __awaiter(void 0, void 0, void 0, fu
                 entry,
                 outputPath,
                 outputFilename: `${id}.js`,
-            }, handoff);
+            }, handoff, inputs);
         }
         catch (e) {
+            if (inputs)
+                inputs.failed = true;
             logger_1.Logger.error(`Failed to bundle JS for component "${id}" (${id}.js):`, e);
             return data;
         }
@@ -113,6 +117,8 @@ const buildComponentJs = (data, handoff) => __awaiter(void 0, void 0, void 0, fu
         }
     }
     catch (e) {
+        if (inputs)
+            inputs.failed = true;
         logger_1.Logger.error(`JS build failed for component "${id}":`, e);
     }
     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,20 @@ 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[]>;
+/**
+ * Every file in the module graph of an entry, stylesheets included, or `null` when the graph does
+ * not build.
+ */
+export declare function collectModuleInputs(entryPath: string, handoff: any): Promise<string[] | null>;
 /**
  * Resolves a module from multiple search directories
  * @param id - Module ID to resolve

package/dist/transformers/utils/build.js

@@ -1,12 +1,36 @@
 "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.collectModuleInputs = collectModuleInputs;
 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 +41,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 +54,81 @@ 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* () {
+        const metafile = yield buildModuleGraph(entryPath, handoff);
+        return metafile ? orderStyleImports(metafile, entryPath) : [];
+    });
+}
+/**
+ * Every file in the module graph of an entry, stylesheets included, or `null` when the graph does
+ * not build.
+ */
+function collectModuleInputs(entryPath, handoff) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const metafile = yield buildModuleGraph(entryPath, handoff);
+        return metafile ? Object.keys(metafile.inputs).map((input) => path_1.default.resolve(input)) : null;
+    });
+}
+function buildModuleGraph(entryPath, handoff) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a, _b, _c;
+        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 (_c = result.metafile) !== null && _c !== void 0 ? _c : null;
+        }
+        catch (_d) {
+            return null;
+        }
+    });
+}
 /**
  * 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: {} };

package/dist/types/config.d.ts

@@ -115,6 +115,100 @@ export interface ConfigCatalog {
 export type RuntimeMode = 'workspace' | 'registry';
 /** Format used when synthesizing local workspace declarations. */
 export type DeclarationFormat = 'ts' | 'js' | 'cjs';
+/** How a connection's credential is supplied. Declared, never inferred from a missing key. */
+export type AiCredentialKind = 'service' | 'user' | 'none';
+/**
+ * An email option: a literal, baked into the build, or an environment reference, read by the deployed
+ * app at request time.
+ */
+export type HandoffEmailOption<T> = T | RuntimeEnvReference<T>;
+interface HandoffEmailBase {
+    /** Sender address, such as `Handoff <no-reply@example.com>`. Use a profile for per-environment values. */
+    from?: string;
+}
+/** Send through an SMTP server, such as Amazon SES, SendGrid, Postmark, Mailgun or Microsoft 365. */
+export interface HandoffSmtpEmail extends HandoffEmailBase {
+    provider: 'smtp';
+    options: {
+        host: HandoffEmailOption<string>;
+        /** @default 465, or 587 when `secure` is false */
+        port?: HandoffEmailOption<number>;
+        /**
+         * Use TLS from the start of the connection. When false, the connection upgrades with STARTTLS if
+         * the server offers it. @default true, or false when `port` is set to a port other than 465
+         */
+        secure?: HandoffEmailOption<boolean>;
+        user?: HandoffEmailOption<string>;
+        /** Environment reference to the SMTP password. */
+        password?: RuntimeEnvReference<string>;
+    };
+}
+/** Send through a server-only module that default-exports a `defineEmailProvider()` result. */
+export interface HandoffCustomEmail extends HandoffEmailBase {
+    provider: 'custom';
+    /** Server-only module path. It must be its own file so the build can trace it into the deployed registry. */
+    module: string;
+    /**
+     * Options passed to the provider factory. Literals are baked. Environment references are resolved
+     * at request time. `apiKey` and `password` must be environment references.
+     */
+    options?: Record<string, unknown>;
+}
+/** Registry email settings. `provider` selects the shape of `options`. */
+export type HandoffEmailConfig = HandoffSmtpEmail | HandoffCustomEmail;
+/**
+ * One AI connection the deployment declares. Connections are the whole surface: a reader can add a
+ * key for a declared connection and nothing else, so the server never calls a URL a reader chose.
+ *
+ * Every connection speaks the OpenAI-compatible `/chat/completions` API. A provider that fits
+ * nothing else names a server-only `module` instead of a `baseUrl`.
+ */
+export interface HandoffAiConnection {
+    /** Stable id. A model is addressed as `<id>/<model>`. */
+    id: string;
+    /** Name shown to a reader in the model picker and on the account page. */
+    label: string;
+    /** OpenAI-compatible base URL, such as `https://api.openai.com/v1`. Omit only when `module` is set. */
+    baseUrl?: string;
+    /**
+     * Server-only module path default-exporting a `defineAiProvider()` result, for a provider that is
+     * not OpenAI-compatible. It must be its own file so the build can trace it into the deployed
+     * registry.
+     */
+    module?: string;
+    /**
+     * Environment reference to the deployment's own key. Its presence makes the connection a service
+     * key: the deployment pays and every reader can use it. The name is baked; the value is read at
+     * request time and never leaves the server.
+     */
+    apiKey?: RuntimeEnvReference<string>;
+    /**
+     * Set to `'user'` when each reader supplies their own key. Without it, a connection that needs a
+     * reader's key looks like one that needs none, and the reader gets a raw 401 instead of an
+     * instruction.
+     */
+    credential?: 'user';
+    /** The models this connection offers. A reader cannot use a model that is not listed. */
+    models?: string[];
+    /**
+     * Options passed to a `module` provider factory. Literals are baked. Environment references are
+     * resolved at request time, so secrets must be environment references.
+     */
+    options?: Record<string, unknown>;
+}
+/**
+ * The AI assistant block. Presence of the block opts the build in, and `enabled: false` turns it
+ * off. Like `mcp`, `enabled` is config-only and baked at build time, so a build without it leaves
+ * out both the chat route and the header control rather than showing a control that fails.
+ */
+export interface HandoffAiConfig {
+    /** @default true when the `ai` block is present */
+    enabled?: boolean;
+    /** Declared connections. Merged by `id` with any supplied through `HANDOFF_AI_CONNECTIONS`. */
+    connections?: HandoffAiConnection[];
+    /** The `<connectionId>/<model>` used when a reader has not picked one. */
+    defaultModel?: string;
+}
 /**
  * User-facing `runtime` configuration block. A single optional block that selects the runtime
  * mode and carries mode-specific host/connection settings.
@@ -135,6 +229,8 @@ export interface HandoffRuntimeConfig {
      * @default true
      */
     mcp?: boolean;
+    /** The docs AI assistant. Omit the block to leave it out of the build. See {@link HandoffAiConfig}. */
+    ai?: HandoffAiConfig;
     /** Workspace-mode settings. */
     workspace?: {
         entries?: ConfigEntries;
@@ -142,9 +238,9 @@ export interface HandoffRuntimeConfig {
     };
     /** Registry-mode host settings. Env-var values are stored as names, never as secrets. */
     registry?: {
-        /** Environment reference to the database URL. @default fromEnv('DATABASE_URL') */
-        databaseUrl?: RuntimeEnvReference<string>;
         database?: {
+            /** Environment reference to the database URL. @default fromEnv('DATABASE_URL') */
+            url?: RuntimeEnvReference<string>;
             /**
              * PostgreSQL is the supported database. `driver` selects the built-in connection driver — how
              * to connect, not which engine — over the same package-owned Postgres schema and migrations.
@@ -159,20 +255,26 @@ export interface HandoffRuntimeConfig {
          */
         assetStorage?: {
             /**
-             * Active storage provider for new uploads. `database` keeps bytes inline in Postgres; use the
-             * pre-packaged `vercel-blob` adapter or a `custom` module for object storage.
+             * Active storage provider for new uploads. `database` keeps bytes inline in Postgres; use a
+             * `custom` module for object storage.
              * @default "database"
              */
-            adapter?: 'database' | 'vercel-blob' | 'custom';
-            /** For `adapter: "custom"` - server-only module path default-exporting a `defineAssetStorage` adapter. */
+            provider?: 'database' | 'custom';
+            /** For `provider: "custom"` - server-only module path default-exporting a `defineStorageProvider()` result. */
             module?: string;
-            /** For `adapter: "vercel-blob"` - environment reference to the Blob read/write token. @default fromEnv('BLOB_READ_WRITE_TOKEN') */
-            token?: RuntimeEnvReference<string>;
             /** Max bytes kept inline in the database `bytea` column (larger uploads are rejected). @default 4194304 */
             maxInlineBytes?: number;
-            /** Non-secret options, JSON-encoded into the bundle. Environment references are rejected. Pass variable names instead. */
+            /**
+             * Options passed to the provider factory. Literals are baked. Environment references are resolved
+             * at request time, so secrets must be environment references.
+             */
             options?: Record<string, unknown>;
         };
+        /**
+         * Invitation and password-reset email. Email stays off until `from` is set and the required
+         * options of the provider have values. Until then, invitation links are shown to an administrator.
+         */
+        email?: HandoffEmailConfig;
     };
     /**
      * Connected-workspace settings pointing at a remote registry. A connected workspace is
@@ -185,11 +287,18 @@ export interface HandoffRuntimeConfig {
         accessToken?: EnvSecret<string>;
     };
 }
+/** Connections to external services. */
+export interface ConfigIntegrations {
+    /** The Figma file that `fetch` reads foundations from. In a terminal, `fetch` asks for an empty value. */
+    figma?: {
+        /** The Figma file ID. @default fromEnv('HANDOFF_FIGMA_PROJECT_ID', { default: null }) */
+        projectId?: EnvValue<string | null>;
+        /** A Figma personal access token. Accepts only an environment reference. @default fromEnv('HANDOFF_DEV_ACCESS_TOKEN', { default: null }) */
+        accessToken?: EnvSecret<string | null>;
+    };
+}
 export interface Config {
-    dev_access_token?: EnvSecret<string | null>;
-    devAccessToken?: EnvSecret<string | null>;
-    figma_project_id?: EnvValue<string | null>;
-    figmaProjectId?: EnvValue<string | null>;
+    integrations?: ConfigIntegrations;
     exportsOutputDirectory?: EnvValue<string>;
     sitesOutputDirectory?: EnvValue<string>;
     useVariables?: EnvValue<boolean>;
@@ -273,6 +382,9 @@ export interface Config {
         validateComponent?: (component: TransformComponentTokensResult) => Promise<Record<string, ValidationResult>>;
         /**
          * Optional hook to override the SSR build configuration used in the ssrRenderPlugin
+         *
+         * Stylesheet loaders are re-applied after this hook, so a `.css`/`.scss`/`.sass` import stays out
+         * of the JavaScript graph whatever the hook returns.
          * @param config - The default esbuild configuration
          * @returns Modified esbuild configuration
          * @example
@@ -286,6 +398,9 @@ export interface Config {
         ssrBuildConfig?: (config: BuildOptions) => BuildOptions;
         /**
          * Optional hook to override the client-side build configuration used in the ssrRenderPlugin
+         *
+         * Stylesheet loaders are re-applied after this hook, so a `.css`/`.scss`/`.sass` import stays out
+         * of the JavaScript graph whatever the hook returns.
          * @param config - The default esbuild configuration
          * @returns Modified esbuild configuration
          * @example
@@ -385,11 +500,13 @@ export interface ClientRuntimeConfig {
     connected: boolean;
 }
 /** Values available after config loading. Deferred references retain their names. */
-export type ResolvedConfig = Omit<Config, 'dev_access_token' | 'devAccessToken' | 'figma_project_id' | 'figmaProjectId' | 'exportsOutputDirectory' | 'sitesOutputDirectory' | 'useVariables' | 'app' | 'runtime'> & {
-    dev_access_token?: string | null;
-    devAccessToken?: string | null;
-    figma_project_id?: string | null;
-    figmaProjectId?: string | null;
+export type ResolvedConfig = Omit<Config, 'integrations' | 'exportsOutputDirectory' | 'sitesOutputDirectory' | 'useVariables' | 'app' | 'runtime'> & {
+    integrations?: {
+        figma?: {
+            projectId?: string | null;
+            accessToken?: string | null;
+        };
+    };
     exportsOutputDirectory?: string;
     sitesOutputDirectory?: string;
     useVariables?: boolean;

package/dist/utils/path.d.ts

@@ -1,8 +1,4 @@
-/**
- * Generates a filesystem-safe directory name from an absolute path
- * @param workingPath - The absolute working path to transform
- * @returns A filesystem-safe string suitable for use as a directory name
- */
+/** `<base name>-<path hash>`; the hash keeps directories with the same base name apart. */
 export declare function generateFilesystemSafeId(workingPath: string): string;
 /**
  * Normalize a filesystem path for cross-platform string comparison.

package/dist/utils/path.js

@@ -8,31 +8,14 @@ exports.normalizePathForCompare = normalizePathForCompare;
 exports.arePathsEqual = arePathsEqual;
 exports.resolveWorkingPath = resolveWorkingPath;
 exports.isPathInside = isPathInside;
+const crypto_1 = require("crypto");
 const path_1 = __importDefault(require("path"));
-/**
- * Generates a filesystem-safe directory name from an absolute path
- * @param workingPath - The absolute working path to transform
- * @returns A filesystem-safe string suitable for use as a directory name
- */
+/** `<base name>-<path hash>`; the hash keeps directories with the same base name apart. */
 function generateFilesystemSafeId(workingPath) {
-    // Normalize path separators to forward slashes for consistent processing
-    let safeId = workingPath.replace(/\\/g, '/');
-    // Replace forward slashes with dashes
-    safeId = safeId.replace(/\//g, '-');
-    // Remove or replace invalid filesystem characters
-    safeId = safeId.replace(/[<>:"|?*\x00]/g, '-');
-    // Remove leading/trailing dashes and spaces
-    safeId = safeId.replace(/^[\s-]+|[\s-]+$/g, '');
-    // Handle Windows reserved names (case-insensitive)
-    const reservedNames = /^(CON|PRN|AUX|NUL|COM[1-9]|LPT[1-9])(\.|$)/i;
-    if (reservedNames.test(safeId)) {
-        safeId = `project-${safeId}`;
-    }
-    // Ensure we have at least one character
-    if (!safeId) {
-        safeId = 'default-project';
-    }
-    return safeId;
+    const baseName = path_1.default.basename(path_1.default.resolve(workingPath));
+    const name = baseName.replace(/[^A-Za-z0-9._-]/g, '-').replace(/^[.-]+|[.-]+$/g, '') || 'project';
+    const hash = (0, crypto_1.createHash)('sha256').update(normalizePathForCompare(workingPath)).digest('hex').slice(0, 8);
+    return `${name}-${hash}`;
 }
 /**
  * Normalize a filesystem path for cross-platform string comparison.

package/docs/api.md

@@ -80,10 +80,12 @@ class constructor
 handoff.fetch();
 ```
 
-Fetch will connect to the defined Figma file id provided in the
-`env`. If no env or file is found, it will interactively request one. Then it
-will export all of the tokens and generated data into an `exported` directory
-in the local working root.
+Fetch reads the Figma file ID and access token from `integrations.figma`. By
+default, they come from `HANDOFF_FIGMA_PROJECT_ID` and
+`HANDOFF_DEV_ACCESS_TOKEN`. In a terminal, fetch asks for an empty value.
+Without a terminal, it throws `HandoffConfigError`. Then it exports all of the
+tokens and generated data into an `exported` directory in the local working
+root.
 
 ### build