handoff-app 2.0.0-9 → 2.0.1

package/src/transformers/preview/component/css.ts

@@ -1,6 +1,7 @@
 import fs from 'fs-extra';
 import path from 'path';
 import { InlineConfig, build as viteBuild } from 'vite';
+import { BuildInputs, withBuildInputs } from '../../../cache/build-inputs';
 import Handoff from '../../../index';
 import { formatDurationMs } from '../../../utils/duration';
 import { Logger } from '../../../utils/logger';
@@ -22,6 +23,7 @@ export const 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 = async ({
   entry,
@@ -29,12 +31,14 @@ const buildCssBundle = async ({
   outputFilename,
   loadPaths,
   handoff,
+  inputs,
 }: {
   entry: string;
   outputPath: string;
   outputFilename: string;
   loadPaths: string[];
   handoff: Handoff;
+  inputs?: BuildInputs;
 }): Promise<void> => {
   // Store the current NODE_ENV value
   const oldNodeEnv = process.env.NODE_ENV;
@@ -85,7 +89,7 @@ const buildCssBundle = async ({
       viteConfig = handoff.config.hooks.cssBuildConfig(viteConfig);
     }
 
-    await viteBuild(viteConfig);
+    await viteBuild(withBuildInputs(viteConfig, inputs));
   } catch (e) {
     Logger.error(`Failed to build CSS for "${entry}"`);
     throw e;
@@ -141,7 +145,7 @@ const writeCombinedStyleEntry = async (sources: string[], outputPath: string, id
   return entryPath;
 };
 
-const buildComponentCss = async (data: TransformComponentTokensResult, handoff: Handoff) => {
+const buildComponentCss = async (data: TransformComponentTokensResult, handoff: Handoff, inputs?: BuildInputs) => {
   const id = data.id;
   Logger.debug(`buildComponentCss`, id);
   const outputPath = getComponentOutputPath(handoff);
@@ -175,7 +179,7 @@ const buildComponentCss = async (data: TransformComponentTokensResult, handoff:
     // Setup SASS load paths
     const loadPaths = [
       path.resolve(handoff.workingPath),
-      path.resolve(handoff.workingPath, handoff.exportsDirectory, handoff.getProjectId()),
+      handoff.getOutputPath(),
       path.resolve(handoff.workingPath, 'node_modules'),
     ];
 
@@ -189,6 +193,7 @@ const buildComponentCss = async (data: TransformComponentTokensResult, handoff:
       outputFilename: `${id}.css`,
       loadPaths,
       handoff,
+      inputs,
     });
 
     // Read the built CSS
@@ -242,7 +247,7 @@ export const buildMainCss = async (handoff: Handoff): Promise<void> => {
         const loadPaths = [
           path.dirname(scssEntry),
           path.resolve(handoff.workingPath),
-          path.resolve(handoff.workingPath, handoff.exportsDirectory, handoff.getProjectId()),
+          handoff.getOutputPath(),
           path.resolve(handoff.workingPath, 'node_modules'),
         ];
 

package/src/transformers/preview/component/html.ts

@@ -1,6 +1,7 @@
 import react from '@vitejs/plugin-react';
 import { Types as CoreTypes } from 'handoff-core';
 import { InlineConfig, PluginOption, build as viteBuild } from 'vite';
+import { BuildInputs, withBuildInputs } from '../../../cache/build-inputs';
 import type { RendererKind, SourceFormat } from '../../../catalog/renderers';
 import Handoff from '../../../index';
 import { Logger } from '../../../utils/logger';
@@ -35,6 +36,7 @@ const RENDERER_PLUGINS: Record<RendererKind, PreviewPlugins> = {
  * @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.
  *
@@ -46,7 +48,8 @@ const RENDERER_PLUGINS: Record<RendererKind, PreviewPlugins> = {
 export const buildPreviews = async (
   data: TransformComponentTokensResult,
   handoff: Handoff,
-  components?: CoreTypes.IDocumentationObject['components']
+  components?: CoreTypes.IDocumentationObject['components'],
+  inputs?: BuildInputs
 ): Promise<TransformComponentTokensResult> => {
   if (!data.entries?.template) return data;
 
@@ -87,8 +90,9 @@ export const buildPreviews = async (
       viteConfig = handoff.config.hooks.htmlBuildConfig(viteConfig);
     }
 
-    await viteBuild(viteConfig);
+    await viteBuild(withBuildInputs(viteConfig, inputs));
   } catch (error) {
+    if (inputs) inputs.failed = true;
     Logger.error(`Error building component previews: ${data.entries.template}`, error);
   } finally {
     // Restore the original NODE_ENV value after vite build completes

package/src/transformers/preview/component/javascript.ts

@@ -1,6 +1,7 @@
 import fs from 'fs-extra';
 import path from 'path';
 import { InlineConfig, build as viteBuild } from 'vite';
+import { BuildInputs, withBuildInputs } from '../../../cache/build-inputs';
 import Handoff from '../../../index';
 import { formatDurationMs } from '../../../utils/duration';
 import { Logger } from '../../../utils/logger';
@@ -17,6 +18,7 @@ export const 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 = async (
   {
@@ -25,7 +27,8 @@ const buildJsBundle = async (
     outputFilename,
     format = 'cjs',
   }: { entry: string; outputPath: string; outputFilename: string; format?: 'cjs' | 'iife' },
-  handoff: Handoff
+  handoff: Handoff,
+  inputs?: BuildInputs
 ) => {
   const absEntryPath = path.resolve(entry);
 
@@ -62,7 +65,7 @@ const buildJsBundle = async (
       viteConfig = handoff.config.hooks.jsBuildConfig(viteConfig);
     }
 
-    await viteBuild(viteConfig);
+    await viteBuild(withBuildInputs(viteConfig, inputs));
   } finally {
     // Restore the original NODE_ENV value after vite build completes
     // This prevents interference with Next.js app building/running processes
@@ -84,7 +87,11 @@ const buildJsBundle = async (
  * @param handoff - The Handoff configuration object
  * @returns The updated component transformation result with JavaScript data
  */
-export const buildComponentJs = async (data: TransformComponentTokensResult, handoff: Handoff): Promise<TransformComponentTokensResult> => {
+export const buildComponentJs = async (
+  data: TransformComponentTokensResult,
+  handoff: Handoff,
+  inputs?: BuildInputs
+): Promise<TransformComponentTokensResult> => {
   const id = data.id;
   const outputPath = getComponentOutputPath(handoff);
   const builtJsPath = path.resolve(outputPath, `${id}.js`);
@@ -111,9 +118,11 @@ export const buildComponentJs = async (data: TransformComponentTokensResult, han
           outputPath,
           outputFilename: `${id}.js`,
         },
-        handoff
+        handoff,
+        inputs
       );
     } catch (e) {
+      if (inputs) inputs.failed = true;
       Logger.error(`Failed to bundle JS for component "${id}" (${id}.js):`, e);
       return data;
     }
@@ -126,6 +135,7 @@ export const buildComponentJs = async (data: TransformComponentTokensResult, han
       delete data['jsCompiled'];
     }
   } catch (e) {
+    if (inputs) inputs.failed = true;
     Logger.error(`JS build failed for component "${id}":`, e);
   }
 

package/src/transformers/utils/build.ts

@@ -31,6 +31,10 @@ export const DEFAULT_SSR_BUILD_CONFIG: esbuild.BuildOptions = {
 
 /**
  * Default esbuild configuration for client builds
+ *
+ * Production React, minified: each client bundle carries its own React copy, and a publish uploads it
+ * with the component and with every pattern that uses it. A development build quickly pushes a pattern
+ * past serverless request body limits.
  */
 export const DEFAULT_CLIENT_BUILD_CONFIG: esbuild.BuildOptions = {
   bundle: true,
@@ -39,7 +43,8 @@ export const DEFAULT_CLIENT_BUILD_CONFIG: esbuild.BuildOptions = {
   platform: 'browser',
   jsx: 'automatic',
   sourcemap: false,
-  minify: false,
+  minify: true,
+  define: { 'process.env.NODE_ENV': '"production"' },
   loader: STYLE_IMPORT_LOADERS,
 };
 
@@ -88,6 +93,20 @@ function orderStyleImports(metafile: esbuild.Metafile, entryPath: string): strin
  * declared entry.
  */
 export async function collectStyleImports(entryPath: string, handoff: any): Promise<string[]> {
+  const metafile = await 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.
+ */
+export async function collectModuleInputs(entryPath: string, handoff: any): Promise<string[] | null> {
+  const metafile = await buildModuleGraph(entryPath, handoff);
+  return metafile ? Object.keys(metafile.inputs).map((input) => path.resolve(input)) : null;
+}
+
+async function buildModuleGraph(entryPath: string, handoff: any): Promise<esbuild.Metafile | null> {
   const baseConfig: esbuild.BuildOptions = {
     ...DEFAULT_SSR_BUILD_CONFIG,
     entryPoints: [entryPath],
@@ -99,10 +118,9 @@ export async function collectStyleImports(entryPath: string, handoff: any): Prom
     // 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) : [];
+    return result.metafile ?? null;
   } catch {
-    return [];
+    return null;
   }
 }
 

package/src/types/config.ts

@@ -115,6 +115,108 @@ 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 +237,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 +246,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 +263,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
@@ -186,11 +296,19 @@ export interface HandoffRuntimeConfig {
   };
 }
 
+/** 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>;
@@ -402,13 +520,14 @@ export interface ClientRuntimeConfig {
 /** 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'
+  | 'integrations'
+  | 'exportsOutputDirectory'
+  | 'sitesOutputDirectory'
+  | 'useVariables'
+  | 'app'
+  | 'runtime'
 > & {
-  dev_access_token?: string | null;
-  devAccessToken?: string | null;
-  figma_project_id?: string | null;
-  figmaProjectId?: string | null;
+  integrations?: { figma?: { projectId?: string | null; accessToken?: string | null } };
   exportsOutputDirectory?: string;
   sitesOutputDirectory?: string;
   useVariables?: boolean;
@@ -418,7 +537,10 @@ export type ResolvedConfig = Omit<
   };
 };
 
-export type ClientConfig = Pick<ResolvedConfig, 'app' | 'exportsOutputDirectory' | 'sitesOutputDirectory' | 'assets_zip_links' | 'useVariables'> & {
+export type ClientConfig = Pick<
+  ResolvedConfig,
+  'app' | 'exportsOutputDirectory' | 'sitesOutputDirectory' | 'assets_zip_links' | 'useVariables'
+> & {
   runtime: ClientRuntimeConfig;
 };
 

package/src/utils/README.md

@@ -8,7 +8,7 @@ Shared utility functions used across the codebase.
 |------|---------|
 | `logger.ts` | `Logger` class — timestamped, color-coded console logging |
 | `filter.ts` | `evaluateFilter()`, `filterAndSort()` — generic object filtering with logical operators |
-| `path.ts` | `generateFilesystemSafeId()` — creates safe directory names from paths |
+| `path.ts` | `generateFilesystemSafeId()` — creates short, safe directory names (base name + path hash) from paths |
 | `fs.ts` | `findFilesByExtension()` — recursive file search by extension |
 | `markdown.ts` | `parseMarkdown()` — frontmatter parse without gray-matter's unbounded module cache |
 | `index.ts` | `filterOutNull()` type guard |

package/src/utils/path.ts

@@ -1,35 +1,12 @@
+import { createHash } from 'crypto';
 import path from '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. */
 export function generateFilesystemSafeId(workingPath: string): string {
-  // 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.basename(path.resolve(workingPath));
+  const name = baseName.replace(/[^A-Za-z0-9._-]/g, '-').replace(/^[.-]+|[.-]+$/g, '') || 'project';
+  const hash = createHash('sha256').update(normalizePathForCompare(workingPath)).digest('hex').slice(0, 8);
+  return `${name}-${hash}`;
 }
 
 /**

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

@@ -46,6 +46,15 @@ const config = {
   // subdirectories are each an item.
   // catalog: { include: ["components", "patterns"] },
 
+  // Figma: `fetch` reads the file ID and token from these variables. Defaults shown. If a value is
+  // empty, `fetch` asks for it. The token accepts only an environment reference.
+  // integrations: {
+  //   figma: {
+  //     projectId: fromEnv("HANDOFF_FIGMA_PROJECT_ID", { default: null }),
+  //     accessToken: fromEnv("HANDOFF_DEV_ACCESS_TOKEN", { default: null }),
+  //   },
+  // },
+
   // `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
@@ -54,8 +63,7 @@ const config = {
     mode: "workspace",
     // mcp: false,
     // registry: {
-    //   databaseUrl: fromEnv("DATABASE_URL"),
-    //   database: { driver: "pg" }, // 'pg' | 'neon'
+    //   database: { url: fromEnv("DATABASE_URL"), driver: "pg" }, // driver: 'pg' | 'neon'
     // },
   },
 

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

@@ -44,6 +44,15 @@ export default defineConfig({
   // subdirectories are each an item.
   // catalog: { include: ["components", "patterns"] },
 
+  // Figma: `fetch` reads the file ID and token from these variables. Defaults shown. If a value is
+  // empty, `fetch` asks for it. The token accepts only an environment reference.
+  // integrations: {
+  //   figma: {
+  //     projectId: fromEnv("HANDOFF_FIGMA_PROJECT_ID", { default: null }),
+  //     accessToken: fromEnv("HANDOFF_DEV_ACCESS_TOKEN", { default: null }),
+  //   },
+  // },
+
   // `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
@@ -52,8 +61,7 @@ export default defineConfig({
     mode: "workspace",
     // mcp: false,
     // registry: {
-    //   databaseUrl: fromEnv("DATABASE_URL"),
-    //   database: { driver: "pg" }, // 'pg' | 'neon'
+    //   database: { url: fromEnv("DATABASE_URL"), driver: "pg" }, // driver: 'pg' | 'neon'
     // },
   },
 

package/templates/default/handoff.config.with-examples.js.tpl

@@ -48,6 +48,15 @@ const config = {
     include: ["components/button"],
   },
 
+  // Figma: `fetch` reads the file ID and token from these variables. Defaults shown. If a value is
+  // empty, `fetch` asks for it. The token accepts only an environment reference.
+  // integrations: {
+  //   figma: {
+  //     projectId: fromEnv("HANDOFF_FIGMA_PROJECT_ID", { default: null }),
+  //     accessToken: fromEnv("HANDOFF_DEV_ACCESS_TOKEN", { default: null }),
+  //   },
+  // },
+
   // `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
@@ -56,8 +65,7 @@ const config = {
     mode: "workspace",
     // mcp: false,
     // registry: {
-    //   databaseUrl: fromEnv("DATABASE_URL"),
-    //   database: { driver: "pg" }, // 'pg' | 'neon'
+    //   database: { url: fromEnv("DATABASE_URL"), driver: "pg" }, // driver: 'pg' | 'neon'
     // },
   },
 

package/templates/default/handoff.config.with-examples.ts.tpl

@@ -46,6 +46,15 @@ export default defineConfig({
     include: ["components/button"],
   },
 
+  // Figma: `fetch` reads the file ID and token from these variables. Defaults shown. If a value is
+  // empty, `fetch` asks for it. The token accepts only an environment reference.
+  // integrations: {
+  //   figma: {
+  //     projectId: fromEnv("HANDOFF_FIGMA_PROJECT_ID", { default: null }),
+  //     accessToken: fromEnv("HANDOFF_DEV_ACCESS_TOKEN", { default: null }),
+  //   },
+  // },
+
   // `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
@@ -54,8 +63,7 @@ export default defineConfig({
     mode: "workspace",
     // mcp: false,
     // registry: {
-    //   databaseUrl: fromEnv("DATABASE_URL"),
-    //   database: { driver: "pg" }, // 'pg' | 'neon'
+    //   database: { url: fromEnv("DATABASE_URL"), driver: "pg" }, // driver: 'pg' | 'neon'
     // },
   },
 

package/templates/default/package.json.tpl

@@ -17,7 +17,7 @@
   "dependencies": {},
   "devDependencies": {},
   "engines": {
-    "node": ">=16.0.0",
-    "npm": ">=8.0.0"
+    "node": ">=22",
+    "npm": ">=10"
   }
 }

package/.editorconfig

@@ -1,19 +0,0 @@
-# EditorConfig is awesome: https://EditorConfig.org
-
-# top-most EditorConfig file
-root = true
-
-[*.{css,scss,sass}]
-charset = utf-8
-indent_style = tab
-indent_size = unset
-end_of_line = lf
-trim_trailing_whitespace = true
-insert_final_newline = true
-
-[*.{js,ts,jsx,tsx}]
-charset = utf-8
-indent_style = space
-end_of_line = lf
-trim_trailing_whitespace = true
-insert_final_newline = true

package/.eslintrc.json

@@ -1,4 +0,0 @@
-{
-  "extends": ["next", "prettier"],
-  "ignorePatterns": ["./src/app/out/**/*", "**/*.js"]
-}

package/.prettierrc.json

@@ -1,8 +0,0 @@
-{
-    "trailingComma": "es5",
-    "semi": true,
-    "tabWidth": 2,
-    "singleQuote": true,
-    "jsxSingleQuote": true,
-    "plugins": ["prettier-plugin-tailwindcss"]
-  }