handoff-app 2.0.0-7 → 2.0.0-9

package/src/transformers/preview/types.ts

@@ -18,6 +18,9 @@ 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';
 }
@@ -27,6 +30,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;
 }
 
@@ -115,6 +120,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;
   };
@@ -192,6 +199,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. */
@@ -212,6 +221,11 @@ export type OptionalPreviewRender = {
   values: { [key: string]: string | string[] | any };
   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/src/transformers/utils/build.ts

@@ -1,6 +1,21 @@
 import esbuild from 'esbuild';
 import path from '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.
+ */
+export const STYLE_IMPORT_LOADERS: Record<string, esbuild.Loader> = Object.fromEntries(
+  STYLE_EXTENSIONS.map((extension) => [extension, 'empty' as esbuild.Loader])
+);
+
 /**
  * Default esbuild configuration for SSR builds
  */
@@ -11,6 +26,7 @@ export const DEFAULT_SSR_BUILD_CONFIG: esbuild.BuildOptions = {
   platform: 'node',
   jsx: 'automatic',
   external: ['react', 'react-dom', '@opentelemetry/api'],
+  loader: STYLE_IMPORT_LOADERS,
 };
 
 /**
@@ -24,8 +40,72 @@ export const DEFAULT_CLIENT_BUILD_CONFIG: esbuild.BuildOptions = {
   jsx: 'automatic',
   sourcemap: false,
   minify: false,
+  loader: STYLE_IMPORT_LOADERS,
 };
 
+/** Apply after a consumer hook: a hook that replaces `loader` would otherwise drop these. */
+export function withStyleLoaders<T extends esbuild.BuildOptions>(config: T): T {
+  return { ...config, loader: { ...config.loader, ...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: esbuild.Metafile, entryPath: string): string[] {
+  const entryKey = Object.keys(metafile.inputs).find((key) => path.resolve(key) === entryPath);
+  if (!entryKey) return [];
+
+  const ordered: string[] = [];
+  const visited = new Set<string>();
+
+  const visit = (key: string) => {
+    if (visited.has(key)) return;
+    visited.add(key);
+
+    for (const imported of metafile.inputs[key]?.imports ?? []) {
+      if (!imported.external && metafile.inputs[imported.path]) visit(imported.path);
+    }
+
+    if (STYLE_EXTENSIONS.includes(path.extname(key))) ordered.push(path.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.
+ */
+export async function collectStyleImports(entryPath: string, handoff: any): Promise<string[]> {
+  const baseConfig: esbuild.BuildOptions = {
+    ...DEFAULT_SSR_BUILD_CONFIG,
+    entryPoints: [entryPath],
+    logLevel: 'silent',
+  };
+  const hookedConfig = handoff?.config?.hooks?.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 = await esbuild.build({ ...withStyleLoaders(hookedConfig), metafile: true });
+
+    return result.metafile ? orderStyleImports(result.metafile, entryPath) : [];
+  } catch {
+    return [];
+  }
+}
+
 /**
  * Resolves a module from multiple search directories
  * @param id - Module ID to resolve

package/src/transformers/utils/module.ts

@@ -1,6 +1,6 @@
 import esbuild from 'esbuild';
 import { ModuleEvaluationResult } from '../types';
-import { DEFAULT_SSR_BUILD_CONFIG } from './build';
+import { DEFAULT_SSR_BUILD_CONFIG, withStyleLoaders } from './build';
 
 function createModuleBuildConfig(entryPath: string, handoff: any): esbuild.BuildOptions {
   const defaultBuildConfig: esbuild.BuildOptions = {
@@ -8,9 +8,11 @@ function createModuleBuildConfig(entryPath: string, handoff: any): esbuild.Build
     entryPoints: [entryPath],
   };
 
-  return handoff.config?.hooks?.ssrBuildConfig
+  const hookedBuildConfig = handoff.config?.hooks?.ssrBuildConfig
     ? handoff.config.hooks.ssrBuildConfig(defaultBuildConfig)
     : defaultBuildConfig;
+
+  return withStyleLoaders(hookedBuildConfig);
 }
 
 function evaluateBuiltModule(code: string): ModuleEvaluationResult {

package/src/types/config.ts

@@ -1,3 +1,4 @@
+import type { EnvValue, EnvSecret, RuntimeEnvReference } from '../config/from-env';
 import { BuildOptions } from 'esbuild';
 import type Handlebars from 'handlebars';
 import { Types as HandoffTypes } from 'handoff-core';
@@ -58,8 +59,8 @@ export type RegisterHandlebarsHelpersContext = {
 
 export interface NextAppConfig {
   theme?: string;
-  title: string;
-  client: string;
+  title?: string;
+  client?: string;
   google_tag_manager?: string | null | undefined;
   googleTagManager?: string | null | undefined;
   type_copy?: string;
@@ -68,15 +69,17 @@ export interface NextAppConfig {
   typeSort?: string[];
   color_sort?: string[];
   colorSort?: string[];
-  breakpoints: Breakpoints;
+  /** Omit to keep the defaults; a declared block merges onto them rather than replacing them. */
+  breakpoints?: Breakpoints;
   component_sort?: string[];
   componentSort?: string[];
   base_path?: string;
   basePath?: string;
-  attribution: boolean;
+  /** @default true */
+  attribution?: boolean;
   ports?: {
-    app: number;
-    websocket: number;
+    app: EnvValue<number>;
+    websocket: EnvValue<number>;
   };
 }
 
@@ -139,13 +142,8 @@ export interface HandoffRuntimeConfig {
   };
   /** Registry-mode host settings. Env-var values are stored as names, never as secrets. */
   registry?: {
-    /** Name of the env var holding the database URL. @default "DATABASE_URL" */
-    databaseUrlEnv?: string;
-    /**
-     * @deprecated Fixed registry secrets are no longer authorized. This option remains parseable
-     * only so existing configuration files do not break.
-     */
-    apiTokenEnv?: string;
+    /** Environment reference to the database URL. @default fromEnv('DATABASE_URL') */
+    databaseUrl?: RuntimeEnvReference<string>;
     database?: {
       /**
        * PostgreSQL is the supported database. `driver` selects the built-in connection driver — how
@@ -168,11 +166,11 @@ export interface HandoffRuntimeConfig {
       adapter?: 'database' | 'vercel-blob' | 'custom';
       /** For `adapter: "custom"` - server-only module path default-exporting a `defineAssetStorage` adapter. */
       module?: string;
-      /** For `adapter: "vercel-blob"` - env var name holding the Blob read/write token. @default "BLOB_READ_WRITE_TOKEN" */
-      tokenEnv?: 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 adapter options (bucket env-var names, region, a custom `providerId`, …). */
+      /** Non-secret options, JSON-encoded into the bundle. Environment references are rejected. Pass variable names instead. */
       options?: Record<string, unknown>;
     };
   };
@@ -181,22 +179,21 @@ export interface HandoffRuntimeConfig {
    * `mode: 'workspace'` plus this block — it is not a third runtime mode.
    */
   registryConnection?: {
-    url?: string;
-    /** @default "HANDOFF_REGISTRY_URL" */
-    urlEnv?: string;
-    /** @default "HANDOFF_REGISTRY_ACCESS_TOKEN" */
-    accessTokenEnv?: string;
+    /** @default fromEnv('HANDOFF_REGISTRY_URL', { default: '' }) */
+    url?: EnvValue<string>;
+    /** @default fromEnv('HANDOFF_REGISTRY_ACCESS_TOKEN', { default: '' }) */
+    accessToken?: EnvSecret<string>;
   };
 }
 
 export interface Config {
-  dev_access_token?: string | null | undefined;
-  devAccessToken?: string | null | undefined;
-  figma_project_id?: string | null | undefined;
-  figmaProjectId?: string | null | undefined;
-  exportsOutputDirectory?: string;
-  sitesOutputDirectory?: string;
-  useVariables?: boolean;
+  dev_access_token?: EnvSecret<string | null>;
+  devAccessToken?: EnvSecret<string | null>;
+  figma_project_id?: EnvValue<string | null>;
+  figmaProjectId?: EnvValue<string | null>;
+  exportsOutputDirectory?: EnvValue<string>;
+  sitesOutputDirectory?: EnvValue<string>;
+  useVariables?: EnvValue<boolean>;
   /**
    * Configuration for React component docs generation (handoff-docgen).
    */
@@ -278,6 +275,9 @@ export interface Config {
 
     /**
      * 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
@@ -292,6 +292,9 @@ export interface Config {
 
     /**
      * 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
@@ -396,7 +399,26 @@ export interface ClientRuntimeConfig {
   connected: boolean;
 }
 
-export type ClientConfig = Pick<Config, 'app' | 'exportsOutputDirectory' | 'sitesOutputDirectory' | 'assets_zip_links' | 'useVariables'> & {
+/** 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;
+  exportsOutputDirectory?: string;
+  sitesOutputDirectory?: string;
+  useVariables?: boolean;
+  app?: Omit<NextAppConfig, 'ports'> & { ports?: { app: number; websocket: number } };
+  runtime?: Omit<HandoffRuntimeConfig, 'registryConnection'> & {
+    registryConnection?: { url?: string; accessToken?: string };
+  };
+};
+
+export type ClientConfig = Pick<ResolvedConfig, 'app' | 'exportsOutputDirectory' | 'sitesOutputDirectory' | 'assets_zip_links' | 'useVariables'> & {
   runtime: ClientRuntimeConfig;
 };
 

package/templates/default/env.tpl

@@ -1,2 +1,12 @@
 HANDOFF_FIGMA_PROJECT_ID={{figmaProjectId}}
 HANDOFF_DEV_ACCESS_TOKEN={{figmaAccessToken}}
+
+# Optional. Select a Handoff configuration profile.
+# HANDOFF_PROFILE=local
+#
+# A selected profile also reads .env.<profile> on top of this file, when that file exists.
+
+# Optional. Connect this workspace to a registry.
+# A token is created in the registry under Account > Access tokens.
+# HANDOFF_REGISTRY_URL=https://registry.example.com
+# HANDOFF_REGISTRY_ACCESS_TOKEN=hnd_...

package/templates/default/gitignore.tpl

@@ -11,8 +11,15 @@ public/api
 
 # Environment
 .env
+.env.*
 .handoff/
 
+# Local configuration profile
+handoff.config.local.ts
+handoff.config.local.js
+handoff.config.local.cjs
+handoff.config.local.json
+
 # Deployment
 .vercel
 

package/templates/default/handoff.config.js.tpl

@@ -1,4 +1,4 @@
-const { defineConfig } = require('handoff-app');
+const { defineConfig, fromEnv } = require('handoff-app');
 /** @typedef {import('handoff-app').Config} HandoffConfig */
 
 /** @type {HandoffConfig} */
@@ -42,181 +42,30 @@ const config = {
     }
   },
 
-  // catalog: {
-  //   /**
-  //    * Directories to search for catalog items. A path is either an item directory or a
-  //    * collection directory whose subdirectories are each treated as an item. An item declares
-  //    * an implementation (React, Handlebars) or a composition of other items.
-  //    */
-  //   include: ["components", "patterns"],
-  // },
-
-  // Runtime settings, all optional. The default is workspace mode with the MCP endpoint served.
-  // `mcp: false` leaves the /api/mcp/ endpoint, and the connect affordance in the docs header, out
-  // of the build; the route then answers 404.
-  // The registry block is only needed when deploying a hosted registry, and is used by
-  // `build --target registry` and `db:migrate`. The default workspace mode uses no database.
-  // Handoff runs on PostgreSQL, and `driver` just picks the connection driver to use, not
-  // the database engine. Secrets are referenced by env var name and never written here.
-  // runtime: {
-  //   mode: "registry",
-  //   mcp: false,
-  //   registry: {
-  //     databaseUrlEnv: "DATABASE_URL",
-  //     database: { driver: "pg" }, // 'pg' | 'neon'
-  //   },
-  // },
-
-  // Optional handoff-docgen settings used by component docs generation
-  // reactDocgen: {
-  //   maxDepth: 7,
-  //   excludeDirectories: ["dist", "build", ".next"]
-  // },
-
-  hooks: {
-    /**
-     * Optional validation callback for components
-     * @param component - The component instance to validate
-     * @returns A record of validation results where keys are validation types and values are detailed validation results
-     *
-     * @example
-     * validateComponent: async (component) => ({
-     *   a11y: {
-     *     description: 'Accessibility validation check',
-     *     passed: true,
-     *     messages: ['No accessibility issues found']
-     *   },
-     *   responsive: {
-     *     description: 'Responsive design validation',
-     *     passed: false,
-     *     messages: ['Component breaks at mobile breakpoint']
-     *   }
-     * })
-     */
-    // validateComponent: async (component) => {
-    //   // Add your custom validation logic here
-    //   return {};
-    // },
-
-    /**
-     * Optional hook to override the SSR build configuration used in the ssrRenderPlugin
-     * @param config - The default esbuild configuration
-     * @returns Modified esbuild configuration
-     *
-     * @example
-     * ssrBuildConfig: (config) => {
-     *   // Modify the esbuild config as needed
-     *   return config;
-     * }
-     */
-    // ssrBuildConfig: (config) => {
-    //   // Add your custom SSR build configuration here
-    //   return config;
-    // },
-
-    /**
-     * Optional hook to override the client-side build configuration used in the ssrRenderPlugin
-     * @param config - The default esbuild configuration
-     * @returns Modified esbuild configuration
-     *
-     * @example
-     * clientBuildConfig: (config) => {
-     *   // Modify the esbuild config as needed
-     *   return config;
-     * }
-     */
-    // clientBuildConfig: (config) => {
-    //   // Add your custom client build configuration here
-    //   return config;
-    // },
+  // Where catalog items live. A path is either an item directory, or a collection directory whose
+  // subdirectories are each an item.
+  // catalog: { include: ["components", "patterns"] },
 
-    /**
-     * Optional hook to specify which export property contains the schema
-     * @param exports - The module exports object containing the schema
-     * @returns The schema object from the exports
-     *
-     * @example
-     * getSchemaFromExports: (exports) => exports.customSchema || exports.default
-     */
-    // getSchemaFromExports: (exports) => {
-    //   // Add your custom schema extraction logic here
-    //   return exports.default;
-    // },
-
-    /**
-     * Optional hook to transform the schema into properties
-     * @param schema - The schema object to transform
-     * @returns The transformed properties object
-     */
-    // schemaToProperties: (schema) => {
-    //   // Add your custom schema to properties transformation here
-    //   return {};
-    // },
-
-    /**
-     * Optional hook to override the JavaScript Vite configuration
-     * @param config - The default Vite configuration
-     * @returns Modified Vite configuration
-     *
-     * @example
-     * jsBuildConfig: (config) => {
-     *   // Modify the Vite config as needed
-     *   return config;
-     * }
-     */
-    // jsBuildConfig: (config) => {
-    //   // Add your custom JavaScript build configuration here
-    //   return config;
-    // },
-
-    /**
-     * Optional hook to override the CSS Vite configuration
-     * @param config - The default Vite configuration
-     * @returns Modified Vite configuration
-     *
-     * @example
-     * cssBuildConfig: (config) => {
-     *   // Modify the Vite config as needed
-     *   return config;
-     * }
-     */
-    // cssBuildConfig: (config) => {
-    //   // Add your custom CSS build configuration here
-    //   return config;
+  // `mode` selects the runtime: "workspace" (no database) or "registry" (Postgres). The registry
+  // block is read only by `build --target registry` and `db:migrate`, and secrets are referenced by
+  // env var name. A named profile (`handoff.config.registry.*`, `--profile registry`) is a good home
+  // for it.
+  runtime: {
+    mode: "workspace",
+    // mcp: false,
+    // registry: {
+    //   databaseUrl: fromEnv("DATABASE_URL"),
+    //   database: { driver: "pg" }, // 'pg' | 'neon'
     // },
+  },
 
-    /**
-     * Optional hook to override the HTML Vite configuration
-     * @param config - The default Vite configuration
-     * @returns Modified Vite configuration
-     *
-     * @example
-     * htmlBuildConfig: (config) => {
-     *   // Modify the Vite config as needed
-     *   return config;
-     * }
-     */
-    // htmlBuildConfig: (config) => {
-    //   // Add your custom HTML build configuration here
-    //   return config;
-    // },
+  // reactDocgen: { maxDepth: 7, excludeDirectories: ["dist", "build", ".next"] },
 
-    /**
-     * Optional hook run after built-in Handlebars helpers (`field`, `eq`) for preview HTML.
-     * @param context.handlebars - Handlebars module (use registerHelper)
-     * @param context.componentId - Current component id
-     * @param context.properties - Slot metadata map from the schema
-     * @param context.injectFieldWrappers - True when generating inspect-mode previews
-     *
-     * @example
-     * registerHandlebarsHelpers: ({ handlebars, componentId }) => {
-     *   handlebars.registerHelper('upperId', () => componentId.toUpperCase());
-     * }
-     */
-    // registerHandlebarsHelpers: ({ handlebars, componentId, properties, injectFieldWrappers }) => {
-    //   // Add your custom Handlebars helpers here
-    // },
-  },
+  // Optional build hooks: component validation, esbuild and Vite config overrides, Handlebars
+  // helper registration. Signatures and examples are on the `Config` type.
+  // hooks: {
+  //   validateComponent: async (component) => ({}),
+  // },
 };
 
 module.exports = defineConfig(config);