handoff-app 2.0.0-9 → 2.0.0

package/src/cache/build-cache.ts

@@ -1,18 +1,20 @@
 import fs from 'fs-extra';
 import path from 'path';
 import Handoff from '../index';
+import { collectModuleInputs } from '../transformers/utils/build';
 import { Logger } from '../utils/logger';
 import { normalizePathForCompare } from '../utils/path';
+import { BuildInputs } from './build-inputs';
 import { computeDirectoryState, computeFileState, directoryStatesMatch, FileState, statesMatch } from './file-state';
 
 /** Current cache format version - bump when structure changes */
-const CACHE_VERSION = '1.0.0';
+const CACHE_VERSION = '2.0.0';
 
 /**
  * Cache entry for a single component
  */
 export interface ComponentCacheEntry {
-  /** File states for all source files of this component */
+  /** File states for the declared source files of this component and every file its last build read */
   files: Record<string, FileState>;
   /** States for template directory files (if templates is a directory) */
   templateDirFiles?: Record<string, FileState>;
@@ -30,8 +32,25 @@ export interface GlobalDepsState {
   globalScss?: FileState;
   /** Global JS entry file state */
   globalJs?: FileState;
+  /** Main config file state. The build hooks are declared there */
+  mainConfig?: FileState;
+  /** Profile config file state */
+  profileConfig?: FileState;
+  /** Selected profile. All profiles write to the same output, so a switch invalidates all of it */
+  profile?: string;
+  /** Lockfile state. It stands in for the files under `node_modules`, which the cache does not track */
+  lockfile?: FileState;
+  /** handoff-app version that built the output */
+  version?: string;
+  /** Base path written into the generated HTML */
+  basePath?: string;
 }
 
+const GLOBAL_FILE_DEPS = ['tokens', 'globalScss', 'globalJs', 'mainConfig', 'profileConfig', 'lockfile'] as const;
+const GLOBAL_VALUE_DEPS = ['profile', 'version', 'basePath'] as const;
+
+const LOCKFILE_NAMES = ['package-lock.json', 'pnpm-lock.yaml', 'yarn.lock', 'bun.lock', 'bun.lockb'];
+
 /**
  * Complete build cache structure
  */
@@ -48,11 +67,9 @@ export interface BuildCache {
  * Gets the path to the build cache file
  */
 export function getCachePath(handoff: Handoff): string {
-  // Two profiles share one project id and can build different output, so the profile has to name
-  // the cache file. One shared cache would serve the other profile's components.
-  const profile = handoff.getProfile();
-  const fileName = profile ? `build-cache.${profile}.json` : 'build-cache.json';
-  return path.resolve(handoff.modulePath, '.handoff', handoff.getProjectId(), '.cache', fileName);
+  // The cache describes the output in the working directory, so it lives there too. A build deletes
+  // the staged app under the package, so a cache there would not survive.
+  return path.resolve(handoff.workingPath, '.handoff', '.cache', 'build-cache.json');
 }
 
 /**
@@ -128,29 +145,64 @@ export async function computeGlobalDepsState(handoff: Handoff): Promise<GlobalDe
     result.globalJs = (await computeFileState(handoff.runtimeConfig.entries.js)) ?? undefined;
   }
 
+  const mainConfigPath = handoff.getMainConfigFilePath();
+  if (mainConfigPath) {
+    result.mainConfig = (await computeFileState(mainConfigPath)) ?? undefined;
+  }
+
+  const profileConfigPath = handoff.getProfileConfigFilePath();
+  if (profileConfigPath) {
+    result.profileConfig = (await computeFileState(profileConfigPath)) ?? undefined;
+  }
+
+  result.profile = handoff.getProfile();
+
+  const lockfilePath = findLockfile(handoff.workingPath);
+  if (lockfilePath) {
+    result.lockfile = (await computeFileState(lockfilePath)) ?? undefined;
+  }
+
+  result.version = await readPackageVersion(handoff);
+  result.basePath = process.env.HANDOFF_APP_BASE_PATH ?? '';
+
   return result;
 }
 
+/** The nearest lockfile, searched up from the working directory so that a monorepo root lockfile is found. */
+function findLockfile(fromDirectory: string): string | undefined {
+  for (let directory = path.resolve(fromDirectory); ; directory = path.dirname(directory)) {
+    const lockfile = LOCKFILE_NAMES.map((name) => path.join(directory, name)).find((file) => fs.existsSync(file));
+    if (lockfile) return lockfile;
+    if (path.dirname(directory) === directory) return undefined;
+  }
+}
+
+async function readPackageVersion(handoff: Handoff): Promise<string | undefined> {
+  try {
+    return (await fs.readJson(path.resolve(handoff.modulePath, 'package.json'))).version;
+  } catch {
+    return undefined;
+  }
+}
+
 /**
  * Checks if global dependencies have changed
  */
 export function haveGlobalDepsChanged(cached: GlobalDepsState | null | undefined, current: GlobalDepsState): boolean {
   if (!cached) return true;
 
-  // Check each global dependency
-  if (!statesMatch(cached.tokens, current.tokens)) {
-    Logger.debug('Global dependency changed: tokens.json');
-    return true;
-  }
-
-  if (!statesMatch(cached.globalScss, current.globalScss)) {
-    Logger.debug('Global dependency changed: global SCSS entry');
-    return true;
+  for (const key of GLOBAL_FILE_DEPS) {
+    if (!statesMatch(cached[key], current[key])) {
+      Logger.debug(`Global dependency changed: ${key}`);
+      return true;
+    }
   }
 
-  if (!statesMatch(cached.globalJs, current.globalJs)) {
-    Logger.debug('Global dependency changed: global JS entry');
-    return true;
+  for (const key of GLOBAL_VALUE_DEPS) {
+    if (cached[key] !== current[key]) {
+      Logger.debug(`Global dependency changed: ${key}`);
+      return true;
+    }
   }
 
   return false;
@@ -274,46 +326,78 @@ export async function computeComponentFileStates(
 }
 
 /**
- * Checks if a component needs to be rebuilt based on file states
+ * Checks if a component needs to be rebuilt based on file states. This also compares the files that
+ * the last build read with their current state on disk.
  */
-export function hasComponentChanged(
+export async function hasComponentChanged(
   cached: ComponentCacheEntry | null | undefined,
   current: { files: Record<string, FileState>; templateDirFiles?: Record<string, FileState> }
-): boolean {
+): Promise<boolean> {
   if (!cached) {
     return true; // No cache entry means new component
   }
 
-  // Check regular files
-  const cachedFiles = Object.keys(cached.files);
-  const currentFiles = Object.keys(current.files);
-
-  // Check if file count changed
-  if (cachedFiles.length !== currentFiles.length) {
-    return true;
+  for (const [file, state] of Object.entries(current.files)) {
+    if (!statesMatch(cached.files[file], state)) {
+      return true;
+    }
   }
 
-  // Check if any files were added or removed
-  const cachedSet = new Set(cachedFiles);
-  for (const file of currentFiles) {
-    if (!cachedSet.has(file)) {
+  for (const [file, state] of Object.entries(cached.files)) {
+    if (!(file in current.files) && !statesMatch(state, await computeFileState(file))) {
       return true;
     }
   }
 
-  // Check if any file states changed
-  for (const file of cachedFiles) {
-    if (!statesMatch(cached.files[file], current.files[file])) {
-      return true;
+  return !directoryStatesMatch(cached.templateDirFiles, current.templateDirFiles);
+}
+
+const SCRIPT_EXTENSIONS = new Set(['.js', '.jsx', '.ts', '.tsx', '.mjs', '.cjs', '.mts', '.cts']);
+
+/**
+ * File states for every file that the builds of a component read, or `null` when that list is
+ * incomplete and the component must not be cached.
+ *
+ * Previews compile their sources with esbuild inside a Vite plugin, so Rollup does not see those
+ * imports. The esbuild graph of each script entry supplies them. The lockfile covers the files under
+ * `node_modules`, so they are skipped, together with the generated files in the output directory.
+ */
+export async function computeBuildInputStates(
+  handoff: Handoff,
+  componentId: string,
+  inputs: BuildInputs
+): Promise<Record<string, FileState> | null> {
+  if (inputs.failed) {
+    return null;
+  }
+
+  const files = new Set(inputs.files);
+  const entries = handoff.runtimeConfig?.entities.components[componentId]?.entries as Record<string, string | undefined> | undefined;
+  const scriptEntries = new Set(Object.values(entries ?? {}).filter((entry): entry is string => !!entry && SCRIPT_EXTENSIONS.has(path.extname(entry))));
+
+  for (const entry of scriptEntries) {
+    const moduleInputs = await collectModuleInputs(entry, handoff);
+    if (!moduleInputs) {
+      return null;
     }
+    for (const file of moduleInputs) files.add(file);
   }
 
-  // Check template directory files if applicable
-  if (!directoryStatesMatch(cached.templateDirFiles, current.templateDirFiles)) {
-    return true;
+  const outputDirectory = path.resolve(handoff.workingPath, 'public/api/component');
+  const states: Record<string, FileState> = {};
+
+  for (const id of files) {
+    const file = id.split('?')[0];
+    if (!path.isAbsolute(file) || file.split(path.sep).includes('node_modules') || file.startsWith(outputDirectory + path.sep)) {
+      continue;
+    }
+    const state = await computeFileState(file);
+    if (state) {
+      states[path.resolve(file)] = state;
+    }
   }
 
-  return false;
+  return states;
 }
 
 /**
@@ -369,10 +453,11 @@ export function createEmptyCache(): BuildCache {
 export function updateComponentCacheEntry(
   cache: BuildCache,
   componentId: string,
-  fileStates: { files: Record<string, FileState>; templateDirFiles?: Record<string, FileState> }
+  fileStates: { files: Record<string, FileState>; templateDirFiles?: Record<string, FileState> },
+  inputStates: Record<string, FileState>
 ): void {
   cache.components[componentId] = {
-    files: fileStates.files,
+    files: { ...inputStates, ...fileStates.files },
     templateDirFiles: fileStates.templateDirFiles,
     buildTimestamp: Date.now(),
   };

package/src/cache/build-inputs.ts

@@ -0,0 +1,28 @@
+import type { InlineConfig, Plugin } from 'vite';
+
+/**
+ * The files that the builds of one component read, so the build cache can tell when an imported
+ * file changes. A failed build can stop before it reads the file that broke it, so its list is
+ * incomplete and must not be cached.
+ */
+export interface BuildInputs {
+  files: Set<string>;
+  failed: boolean;
+}
+
+export const createBuildInputs = (): BuildInputs => ({ files: new Set(), failed: false });
+
+/**
+ * Records every file that a Vite build loaded, Sass partials included. The Vite CSS plugin registers
+ * partials with `addWatchFile`, and Rollup keeps this list in every build, not only in watch mode.
+ */
+const collectBuildInputs = (inputs: BuildInputs): Plugin => ({
+  name: 'handoff:collect-build-inputs',
+  buildEnd() {
+    for (const file of this.getWatchFiles()) inputs.files.add(file);
+  },
+});
+
+/** Call after the consumer hooks, so that a hook that replaces `plugins` cannot drop the collector. */
+export const withBuildInputs = (config: InlineConfig, inputs?: BuildInputs): InlineConfig =>
+  inputs ? { ...config, plugins: [...(config.plugins ?? []), collectBuildInputs(inputs)] } : config;

package/src/cache/index.ts

@@ -4,6 +4,7 @@ export { computeDirectoryState, computeFileState, directoryStatesMatch, statesMa
 // Build cache utilities
 export {
   checkOutputExists,
+  computeBuildInputStates,
   computeComponentFileStates,
   computeGlobalDepsState,
   createEmptyCache,
@@ -18,3 +19,6 @@ export {
   type ComponentCacheEntry,
   type GlobalDepsState,
 } from './build-cache';
+
+// Build input collection
+export { createBuildInputs, type BuildInputs } from './build-inputs';

package/src/cli/create.ts

@@ -125,8 +125,7 @@ const renderTemplate = (content: string, data: CreateOptions): string => {
 };
 
 const getDependenciesToInstall = (options: CreateOptions): { dependencies: string[]; devDependencies: string[] } => {
-  // TODO: switch back to `handoff-app@latest` before the 2.0 stable release.
-  const dependencies = ['handoff-app@next'];
+  const dependencies = ['handoff-app@latest'];
   const devDependencies: string[] = [];
 
   if (options.includeExamples) {

package/src/commands/build/index.ts

@@ -17,7 +17,7 @@ export interface BuildArgs extends SharedArgs {
  * `handoff-app build [--target static|registry] [--package standalone|vercel]` — builds the
  * documentation site for the resolved target and packages it for the resolved deliverable.
  * `--target` selects *what* is built; the optional, additive `--package` selects *how* it is
- * packaged. Bare `build` resolves to the static target with the `out/<projectId>` export;
+ * packaged. Bare `build` resolves to the static target with the `out/static` export;
  * `--package` never implies a `--target`.
  */
 const command: CommandModule<{}, BuildArgs> = {

package/src/config/README.md

@@ -8,24 +8,22 @@ Handles loading, validation, and resolution of handoff configuration.
 |------|---------|
 | `defaults.ts` | Default config values and `getClientConfig()` for the Next.js app |
 | `from-env.ts` | JSON-compatible environment markers and public types |
-| `resolve-env.ts` | Resolves merged environment references and guards reference-only properties |
+| `resolve-env.ts` | Resolves merged environment references and guards reference-only properties, whose paths accept a `*` segment to cover list elements |
 | `errors.ts` | Shared `HandoffConfigError` |
 | `env.ts` | Reads `.env` at load, then `loadProfileEnv()` applies `.env.<profile>` on top |
 | `loader.ts` | `initConfig()` — reads `handoff.config.ts/.js/.cjs/.json` (in that order) plus the selected profile sidecar, warns on conflicts, and merges every layer |
 | `runtime.ts` | `initRuntimeConfig()` — one pass over every registered catalog directory: loads each declaration, normalizes it into a component or pattern record, skips a declaration with a taken id, resolves SCSS/JS paths and transformer options |
 | `catalog-include.ts` | `isIncluded()` / `addToCatalog()` — registers a directory under `catalog.include` |
-| `validator.ts` | `validateConfig()` — ensures required Figma credentials are present |
 | `helpers.ts` | `defineConfig()` — typed authoring; maps camelCase keys to the runtime keys |
 | `index.ts` | Barrel re-exports |
 
 ## Usage
 
 ```ts
-import { initConfig, initRuntimeConfig, validateConfig } from './config';
+import { initConfig, initRuntimeConfig } from './config';
 
 const config = initConfig(overrides);
 const [runtimeConfig, configPaths] = initRuntimeConfig({ config, workingPath });
-const validated = validateConfig(config);
 ```
 
 ## Main Config Precedence
@@ -70,7 +68,7 @@ property path, variable name, and active profile. Invalid names and rejected lit
 `EnvValue<T>` accepts a literal or reference. `EnvSecret<T>` accepts only a reference and resolves
 at config load. Secret defaults can only be empty or null, for optional credentials.
 `RuntimeEnvReference<T>` accepts only a reference with no default. Its name survives config loading and
-is read in the deployed process. Database URLs and asset-storage tokens are deferred.
+is read in the deployed process. Database URLs, asset-storage tokens, email secrets, and AI keys are deferred.
 
 The loader resolves references once after all layers merge, before other config guards.
 References replace whole values, including earlier references and their defaults. A profile can
@@ -83,10 +81,13 @@ numeric and boolean properties also retain their default's conversion when a ref
 fallback. Booleans are true only for `true`. Numbers must be finite. A lower-layer fallback never
 becomes the fallback for a replacement reference.
 
-`runtime.registry.assetStorage.options` is for non-secret values only. Its resolved contents are
-JSON-encoded into the bundle, so the loader rejects an environment reference anywhere inside it
-(`BAKED_PATHS`). For custom adapter secrets, put a variable name in options and read it through the
-adapter factory's `env` argument at runtime. A per-environment literal belongs in a profile.
+`runtime.registry.email.options`, `runtime.registry.assetStorage.options`, and
+`runtime.ai.connections.*.options` are deferred prefixes (`DEFERRED_PREFIXES`). A reference anywhere
+inside them keeps its name, and the deployed app resolves it with `resolveEnvReferences()` before it
+calls the module factory. Literals are baked. `email.options.apiKey` and `email.options.password` are
+also `DEFERRED_PATHS`, so a literal secret is rejected for every email provider. Before the merge, a
+layer that changes `email.provider` drops `options` and `module` from the lower layers, so the
+settings of two providers never mix.
 
 `ResolvedConfig` narrows eager properties by hand. Adding an eager property requires its `Config`
 member and resolved narrowing. A secret also needs a `SECRET_PATHS` entry for untyped configs.

package/src/config/defaults.ts

@@ -15,8 +15,12 @@ export const isMcpEnabled = (config: Pick<Config, 'runtime'> | Pick<ResolvedConf
   config?.runtime?.mcp !== false;
 
 export const defaultConfig = (): Config => ({
-  dev_access_token: fromEnv('HANDOFF_DEV_ACCESS_TOKEN', { default: null }),
-  figma_project_id: fromEnv('HANDOFF_FIGMA_PROJECT_ID', { default: null }),
+  integrations: {
+    figma: {
+      projectId: fromEnv('HANDOFF_FIGMA_PROJECT_ID', { default: null }),
+      accessToken: fromEnv('HANDOFF_DEV_ACCESS_TOKEN', { default: null }),
+    },
+  },
   runtime: {
     mode: 'workspace',
     registryConnection: {
@@ -24,8 +28,7 @@ export const defaultConfig = (): Config => ({
       accessToken: fromEnv('HANDOFF_REGISTRY_ACCESS_TOKEN', { default: '' }),
     },
     registry: {
-      databaseUrl: fromEnv('DATABASE_URL'),
-      assetStorage: { token: fromEnv('BLOB_READ_WRITE_TOKEN') },
+      database: { url: fromEnv('DATABASE_URL') },
     },
   },
   exportsOutputDirectory: fromEnv('HANDOFF_OUTPUT_DIR', { default: 'exported' }),

package/src/config/from-env.ts

@@ -24,3 +24,36 @@ export const fromEnv = <T = string>(name: string, options?: { default: T }): Env
 
 export const isEnvReference = (value: unknown): value is EnvReference<unknown> =>
   value !== null && typeof value === 'object' && Object.prototype.hasOwnProperty.call(value, '$env');
+
+const isPlainRecord = (value: unknown): value is Record<string, unknown> =>
+  value !== null && typeof value === 'object' && !Array.isArray(value);
+
+/** Replace each reference nested in `options` with its value from `env`. An unset or empty variable becomes `undefined`. */
+export const resolveEnvReferences = (options: Record<string, unknown>, env: NodeJS.ProcessEnv): Record<string, unknown> => {
+  const resolve = (value: unknown): unknown => {
+    if (isEnvReference(value)) {
+      const resolved = typeof value.$env === 'string' ? env[value.$env]?.trim() : undefined;
+      return resolved || undefined;
+    }
+    if (Array.isArray(value)) return value.map(resolve);
+    if (isPlainRecord(value)) return Object.fromEntries(Object.entries(value).map(([key, entry]) => [key, resolve(entry)]));
+    return value;
+  };
+  return resolve(options) as Record<string, unknown>;
+};
+
+/** The variable names that the references nested in `options` use, for deployment instructions. */
+export const envReferenceNames = (options: Record<string, unknown>): string[] => {
+  const names = new Set<string>();
+  const collect = (value: unknown): void => {
+    if (isEnvReference(value)) {
+      if (typeof value.$env === 'string') names.add(value.$env);
+    } else if (Array.isArray(value)) {
+      value.forEach(collect);
+    } else if (isPlainRecord(value)) {
+      Object.values(value).forEach(collect);
+    }
+  };
+  collect(options);
+  return [...names];
+};

package/src/config/helpers.ts

@@ -25,12 +25,10 @@ const normalizeAppConfig = (app?: Config['app']): Config['app'] => {
 };
 
 export const normalizeConfig = (config: Config): Config => {
-  const { devAccessToken, figmaProjectId, assetsZipLinks, app, ...rest } = config;
+  const { assetsZipLinks, app, ...rest } = config;
 
   return {
     ...(rest as Config),
-    dev_access_token: devAccessToken !== undefined ? devAccessToken : config.dev_access_token,
-    figma_project_id: figmaProjectId !== undefined ? figmaProjectId : config.figma_project_id,
     assets_zip_links: assetsZipLinks ?? config.assets_zip_links,
     app: normalizeAppConfig(app),
   };

package/src/config/index.ts

@@ -15,9 +15,6 @@ export { defineConfig } from './helpers';
 // Runtime config resolution
 export { initRuntimeConfig } from './runtime';
 
-// Config validation
-export { validateConfig } from './validator';
-
 // Registering catalog item directories under `catalog.include`
 export { addToCatalog, isIncluded } from './catalog-include';
 export type { AddToCatalogResult } from './catalog-include';

package/src/config/loader.ts

@@ -2,9 +2,10 @@ import esbuild from 'esbuild';
 import { STYLE_IMPORT_LOADERS } from '../transformers/utils/build';
 import fs from 'fs-extra';
 import mergeWith from 'lodash/mergeWith';
+import omit from 'lodash/omit';
 import { createRequire } from 'module';
 import path from 'path';
-import { Config, ResolvedConfig } from '../types/config';
+import { Config, HandoffEmailConfig, ResolvedConfig } from '../types/config';
 import { Logger } from '../utils/logger';
 import { resolveWorkingPath } from '../utils/path';
 import { defaultConfig } from './defaults';
@@ -65,7 +66,7 @@ const evaluateTypeScriptConfig = (filePath: string, handoffModulePath: string):
     write: false,
     platform: 'node',
     format: 'cjs',
-    target: 'node16',
+    target: 'node22',
     logLevel: 'silent',
     external: ['handoff-app'],
     loader: STYLE_IMPORT_LOADERS,
@@ -233,6 +234,27 @@ const replaceValues = (destination: unknown, source: unknown) => {
   return Array.isArray(source) || isEnvReference(source) || isEnvReference(destination) ? source : undefined;
 };
 
+/**
+ * A layer that changes `runtime.registry.email.provider` starts from fresh `options` and `module`, so
+ * the deep merge never mixes the settings of two providers.
+ */
+const resetEmailOnProviderChange = (layers: Partial<Config>[]): Partial<Config>[] => {
+  let provider: string | undefined;
+  let start = 0;
+  layers.forEach((layer, index) => {
+    const next = layer.runtime?.registry?.email?.provider;
+    if (next !== undefined && next !== provider) {
+      provider = next;
+      start = index;
+    }
+  });
+  return layers.map((layer, index) => {
+    const email = layer.runtime?.registry?.email;
+    if (index >= start || !email) return layer;
+    return { ...layer, runtime: { ...layer.runtime, registry: { ...layer.runtime!.registry, email: omit(email, ['options', 'module']) as HandoffEmailConfig } } };
+  });
+};
+
 /**
  * Loads the handoff configuration for the given working directory and returns metadata.
  */
@@ -264,7 +286,7 @@ export const initConfigWithMetadata = (configOverride?: Partial<Config>, context
   Logger.debug(`Config profile: ${profileLabel}`);
   Logger.debug(`Config files loaded: ${[configPath, profileConfigPath].filter(Boolean).join(', ') || 'none, using defaults'}`);
 
-  const merged = mergeWith({}, ...layers, replaceValues) as Config;
+  const merged = mergeWith({}, ...resetEmailOnProviderChange(layers), replaceValues) as Config;
   const config = resolveConfigEnv(merged, profileSelection?.name, layers[0]);
 
   // Guards run on the resolved config so a profile cannot slip a removed setting past them.

package/src/config/resolve-env.ts

@@ -4,11 +4,32 @@ import { Logger } from '../utils/logger';
 import { isEnvReference } from './from-env';
 import { HandoffConfigError } from './errors';
 
-export const DEFERRED_PATHS = new Set(['runtime.registry.databaseUrl', 'runtime.registry.assetStorage.token']);
-const SECRET_PATHS = new Set(['dev_access_token', 'devAccessToken', 'runtime.registryConnection.accessToken']);
-/** Path prefixes whose resolved contents are JSON-baked into the bundle, so a reference would bake its value. */
-const BAKED_PATHS = ['runtime.registry.assetStorage.options'];
-const isBaked = (path: string): boolean => BAKED_PATHS.some((baked) => path === baked || path.startsWith(`${baked}.`));
+/**
+ * Match a dot path against a pattern. A `*` segment matches exactly one segment, so one pattern
+ * covers every element of a list. With `prefix`, the pattern also matches anything nested under it.
+ */
+const pathMatches = (pattern: string, path: string, prefix = false): boolean => {
+  const expected = pattern.split('.');
+  const actual = path.split('.');
+  if (prefix ? expected.length > actual.length : expected.length !== actual.length) return false;
+  return expected.every((segment, index) => segment === '*' || segment === actual[index]);
+};
+
+/** Paths whose value the deployed app reads at request time, so only the variable name is stored. */
+export const DEFERRED_PATHS = [
+  'runtime.registry.database.url',
+  'runtime.registry.email.options.apiKey',
+  'runtime.registry.email.options.password',
+  'runtime.ai.connections.*.apiKey',
+];
+/**
+ * Path prefixes whose nested references the deployed app reads at request time. Literals below them
+ * are baked. `DEFERRED_PATHS` entries below them still reject literals.
+ */
+const DEFERRED_PREFIXES = ['runtime.registry.email.options', 'runtime.registry.assetStorage.options', 'runtime.ai.connections.*.options'];
+const SECRET_PATHS = new Set(['integrations.figma.accessToken', 'runtime.registryConnection.accessToken']);
+const isDeferred = (path: string): boolean => DEFERRED_PATHS.some((deferred) => pathMatches(deferred, path));
+const isUnderDeferredPrefix = (path: string): boolean => DEFERRED_PREFIXES.some((prefix) => pathMatches(`${prefix}.*`, path, true));
 const ENV_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
 const ALIASES: Record<string, string> = {
   HANDOFF_REGISTRY_URL: 'HANDOFF_CLOUD_URL',
@@ -40,20 +61,12 @@ export const resolveConfigEnv = (config: Config, profile?: string, defaults?: Co
     throw new HandoffConfigError(`Config "${path}" (profile "${profile ?? 'default'}"): ${message}`);
   };
   const walk = (value: unknown, path: string, seed?: unknown): unknown => {
-    const deferred = DEFERRED_PATHS.has(path);
+    const deferred = isDeferred(path);
     const secret = SECRET_PATHS.has(path);
     if ((secret || deferred) && value !== undefined && !isEnvReference(value)) {
       fail(path, 'Expected an environment reference, such as { $env: "VARIABLE_NAME" }. Literal values are not allowed.');
     }
     if (isEnvReference(value)) {
-      // Checked before the name, so the message names the supported pattern instead of the reference shape.
-      if (isBaked(path)) {
-        fail(
-          path,
-          'Environment references are not allowed here because the resolved value is baked into the build. ' +
-            "Put the variable name in options and read it through the adapter factory's `env` argument."
-        );
-      }
       if (typeof value.$env !== 'string' || !ENV_NAME.test(value.$env)) {
         fail(path, 'Invalid environment variable name. Use letters, digits, and underscores, starting with a letter or underscore.');
       }
@@ -62,7 +75,7 @@ export const resolveConfigEnv = (config: Config, profile?: string, defaults?: Co
       if (Object.keys(value).some((key) => key !== '$env' && key !== 'default')) {
         fail(path, `Environment variable "${name}" has an invalid reference shape.`);
       }
-      if (deferred) {
+      if (deferred || isUnderDeferredPrefix(path)) {
         if ('default' in value) fail(path, `Environment variable "${name}" cannot have a default because it is read by the deployed app.`);
         return { $env: name };
       }

package/src/config/runtime.ts

@@ -72,7 +72,7 @@ const evaluateDeclaration = (filePath: string, handoffModulePath: string): any =
     write: false,
     platform: 'node',
     format: 'cjs',
-    target: 'node16',
+    target: 'node22',
     logLevel: 'silent',
     jsx: 'automatic',
     external: ['react', 'react-dom', 'handoff-app'],