handoff-app 2.0.0-9 → 2.0.1

package/src/registry/db/driver.ts

@@ -36,7 +36,7 @@ export interface ResolvedRegistryDatabase {
 
 /** Resolve the env-var name holding the database URL (defaults to `DATABASE_URL`). */
 export const resolveDatabaseUrlEnv = (config: ResolvedConfig | null | undefined): string => {
-  const configured = config?.runtime?.registry?.databaseUrl?.$env?.trim();
+  const configured = config?.runtime?.registry?.database?.url?.$env?.trim();
   return configured || DEFAULT_DATABASE_URL_ENV;
 };
 
@@ -58,7 +58,7 @@ export const resolveRegistryDatabase = (config: ResolvedConfig | null | undefine
   if (!connectionString) {
     throw new Error(
       `Registry database URL is not configured. Set the "${databaseUrlEnv}" environment variable to a ` +
-        `PostgreSQL connection string (or change "runtime.registry.databaseUrl" to point at the env var you use).`
+        `PostgreSQL connection string (or change "runtime.registry.database.url" to point at the env var you use).`
     );
   }
 

package/src/registry/db/schema.ts

@@ -30,7 +30,7 @@ import type { TokenSetKind } from '../tokens/sets';
 
 /**
  * PostgreSQL `bytea` column. Drizzle pg-core has no built-in binary type, so declare it once here.
- * Reads/writes are Node `Buffer`s. The default asset storage adapter keeps small/ordinary asset
+ * Reads/writes are Node `Buffer`s. The default asset storage provider keeps small/ordinary asset
  * bytes inline in this column; larger assets are offloaded to an object-storage `storageRef` instead.
  */
 const bytea = customType<{ data: Buffer; driverData: Buffer }>({
@@ -39,8 +39,8 @@ const bytea = customType<{ data: Buffer; driverData: Buffer }>({
   },
 });
 
-/** Where an asset blob's bytes physically live: the default DB adapter, Vercel Blob, or a custom id. */
-export type AssetStorageProvider = 'database' | 'vercel-blob' | (string & {});
+/** Where an asset blob's bytes live: inline in the database (`database`) or in a custom provider (`custom`). */
+export type AssetStorageProvider = 'database' | 'custom';
 import type { ComponentListObject, PageListObject, PatternComponentEntry, PatternListObject } from '../../transformers/preview/types';
 
 /** Registry account role. Administrators may issue write-scoped credentials. */
@@ -112,6 +112,8 @@ export const components = pgTable(
     sourceFormat: text('source_format'),
     tags: jsonb('tags').$type<string[]>(),
     categories: jsonb('categories').$type<string[]>(),
+    /** Workspace-relative directory the component was published from. */
+    sourceDir: text('source_dir'),
     /** Full normalized component record. */
     record: jsonb('record').$type<ComponentListObject>().notNull(),
     /** Registry-only review/catalog metadata (management-API allowlist; never a render input). */
@@ -165,6 +167,8 @@ export const patterns = pgTable(
     tags: jsonb('tags').$type<string[]>(),
     /** Pattern component references. */
     components: jsonb('components').$type<PatternComponentEntry[]>(),
+    /** Workspace-relative directory the pattern was published from. */
+    sourceDir: text('source_dir'),
     /** Full normalized pattern record. */
     record: jsonb('record').$type<PatternListObject>().notNull(),
     /** Registry-only review/catalog metadata (management-API allowlist; never a render input). */
@@ -378,23 +382,20 @@ export const tokenArtifacts = pgTable(
  * collection is its current manifest. Publish replaces those rows atomically, so readers always see a
  * complete manifest.
  */
-export const assetCollections = pgTable(
-  'asset_collections',
-  {
-    /** Stable collection id (`icons`|`logos`|`fonts`). Join key across stores. */
-    collection: text('collection').primaryKey(),
-    /** Deterministic content hash over the collection's `(path, contentHash)` manifest (skip-unchanged). */
-    sourceHash: text('source_hash'),
-    /** Build/publish status for the collection. */
-    status: text('status').$type<RegistryBuildStatus>(),
-    builtAt: timestamp('built_at', { withTimezone: true }),
-    builderVersion: text('builder_version'),
-    /** Registry-only review/catalog metadata (parity with other entities; management-API only). */
-    metadata: jsonb('metadata').$type<RegistryReviewMetadata>(),
-    createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
-    updatedAt: timestamp('updated_at', { withTimezone: true }).notNull().defaultNow(),
-  }
-);
+export const assetCollections = pgTable('asset_collections', {
+  /** Stable collection id (`icons`|`logos`|`fonts`). Join key across stores. */
+  collection: text('collection').primaryKey(),
+  /** Deterministic content hash over the collection's `(path, contentHash)` manifest (skip-unchanged). */
+  sourceHash: text('source_hash'),
+  /** Build/publish status for the collection. */
+  status: text('status').$type<RegistryBuildStatus>(),
+  builtAt: timestamp('built_at', { withTimezone: true }),
+  builderVersion: text('builder_version'),
+  /** Registry-only review/catalog metadata (parity with other entities; management-API only). */
+  metadata: jsonb('metadata').$type<RegistryReviewMetadata>(),
+  createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
+  updatedAt: timestamp('updated_at', { withTimezone: true }).notNull().defaultNow(),
+});
 
 /**
  * Logical asset metadata - the collection manifest. One row per asset (icon/logo SVG, sprite,
@@ -431,13 +432,13 @@ export const assets = pgTable(
 /**
  * Content-addressed binary blob store, shared across assets/collections (the `hash` is the blob
  * identity, so an unchanged file re-references the same row). Exactly one location is active per row:
- * inline `content` (bytea, default DB adapter) or an external `storageRef` resolved through the
+ * inline `content` (bytea, default `database` provider) or an external `storageRef` resolved through the
  * recorded `storageProvider`. Both nullable so DB- and object-backed blobs coexist.
  */
 export const assetBlobs = pgTable('asset_blobs', {
   /** SHA-256 of the blob bytes (hex). */
   hash: text('hash').primaryKey(),
-  /** Which storage backed this blob when it was written (`database`|`vercel-blob`|custom id). */
+  /** Which storage backed this blob when it was written (`database`|custom id). */
   storageProvider: text('storage_provider').$type<AssetStorageProvider>().notNull(),
   /** Inline bytes; null when stored externally via `storageRef`. */
   content: bytea('content'),
@@ -575,6 +576,31 @@ export const registryDeviceAuthorizations = pgTable(
   ]
 );
 
+/**
+ * One reader's key for one declared AI connection. Unlike every other credential here the value
+ * must be recoverable, because it is sent to the provider on that reader's behalf, so it is
+ * encrypted rather than hashed (see `../auth/crypto`). A row whose `connectionId` no longer appears
+ * in the config is ignored, not deleted: the connection may come back on the next deploy.
+ */
+export const registryAiKeys = pgTable(
+  'registry_ai_keys',
+  {
+    userId: text('user_id')
+      .notNull()
+      .references(() => registryUsers.id, { onDelete: 'cascade' }),
+    /** Id of the connection the config declares. Never a reader-supplied endpoint. */
+    connectionId: text('connection_id').notNull(),
+    /** Self-describing AES-256-GCM payload; the deployment secret it is keyed from is never stored. */
+    encryptedKey: text('encrypted_key').notNull(),
+    createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
+    updatedAt: timestamp('updated_at', { withTimezone: true }).notNull().defaultNow(),
+  },
+  (table) => [
+    primaryKey({ columns: [table.userId, table.connectionId] }),
+    check('registry_ai_keys_connection_not_blank', sql`length(btrim(${table.connectionId})) > 0`),
+  ]
+);
+
 /**
  * Fixed-window throttling counters. Callers pass a hash of the identifying value so raw emails and
  * IP addresses are not retained.
@@ -616,6 +642,7 @@ export const registrySchema = {
   registryInstallations,
   registryAuthActionTokens,
   registryAccessTokens,
+  registryAiKeys,
   registryDeviceAuthorizations,
   registryAuthRateLimits,
 };

package/src/registry/email/define.ts

@@ -0,0 +1,15 @@
+/**
+ * Typed identity helper for custom email providers (mirrors `defineStorageProvider`): a consumer
+ * default-exports its result from a **server-only** module and points `runtime.registry.email.module`
+ * at it. It must be its own module (not an inline `defineConfig` function) so the build can trace it
+ * into the deployed registry. The default export may be the provider object, or a factory
+ * `(context) => EmailProvider` when it needs its options or env.
+ */
+
+import type { EmailProvider, EmailProviderFactory } from './types';
+
+export function defineEmailProvider(provider: EmailProvider): EmailProvider;
+export function defineEmailProvider(factory: EmailProviderFactory): EmailProviderFactory;
+export function defineEmailProvider(input: EmailProvider | EmailProviderFactory): EmailProvider | EmailProviderFactory {
+  return input;
+}

package/src/registry/email/providers/smtp.ts

@@ -0,0 +1,39 @@
+/**
+ * Built-in SMTP provider, selected with `runtime.registry.email.provider: "smtp"`.
+ *
+ * `nodemailer` is loaded lazily so it is only pulled into memory (and traced into the registry
+ * bundle) when this provider is selected. Options may come from environment variables, so numbers
+ * and booleans can arrive as strings.
+ */
+
+import type { EmailProvider } from '../types';
+
+const toNumber = (value: unknown): number | undefined => {
+  const number = typeof value === 'number' ? value : typeof value === 'string' && value.trim() ? Number(value) : NaN;
+  return Number.isFinite(number) ? number : undefined;
+};
+
+const toBoolean = (value: unknown): boolean | undefined =>
+  typeof value === 'boolean' ? value : typeof value === 'string' && value.trim() ? value.trim() === 'true' : undefined;
+
+/** Build an SMTP provider from options whose references are already resolved. */
+export const createSmtpProvider = (options: Record<string, unknown>): EmailProvider => {
+  const host = typeof options.host === 'string' ? options.host : '';
+  const configuredPort = toNumber(options.port);
+  const secure = toBoolean(options.secure) ?? (configuredPort === undefined || configuredPort === 465);
+  const port = configuredPort ?? (secure ? 465 : 587);
+  const user = typeof options.user === 'string' ? options.user : undefined;
+  const password = typeof options.password === 'string' ? options.password : undefined;
+
+  return {
+    async send({ from, to, subject, html, text }) {
+      if (!host) throw new Error('The SMTP host is not set.');
+      const { createTransport } = await import('nodemailer');
+      const transport = createTransport({ host, port, secure, auth: user ? { user, pass: password } : undefined });
+      const info = await transport.sendMail({ from, to, subject, html, text });
+      if (info.rejected?.length) {
+        throw new Error(`The SMTP server rejected the recipient: ${info.response}`);
+      }
+    },
+  };
+};

package/src/registry/email/resolve.ts

@@ -0,0 +1,94 @@
+/**
+ * Registry email settings resolution.
+ *
+ * `runtime.registry.email.provider` selects the built-in `smtp` provider or a `custom` module. Without
+ * an email block, email delivery is off. The build bakes the provider, the module location, and the
+ * options. An option literal is baked as it is. An environment reference stays `{ $env }` and is
+ * resolved at request time.
+ */
+
+import { HandoffConfigError } from '../../config/errors';
+import type { ResolvedConfig } from '../../types/config';
+
+export type EmailProviderKind = 'smtp' | 'custom';
+
+const PROVIDERS: readonly EmailProviderKind[] = ['smtp', 'custom'];
+
+/** The options each built-in provider accepts. A custom provider accepts any. */
+const BUILT_IN_OPTIONS: Record<Exclude<EmailProviderKind, 'custom'>, readonly string[]> = {
+  smtp: ['host', 'port', 'secure', 'user', 'password'],
+};
+
+/** Email settings as they are baked: literals and `{ $env }` references, never secret values. */
+export interface EmailSettings {
+  from?: string;
+  /** Unset when the config has no email block. */
+  provider?: EmailProviderKind;
+  /** For `custom`: the server-only provider module path. */
+  module?: string;
+  options: Record<string, unknown>;
+}
+
+const isPlainRecord = (value: unknown): value is Record<string, unknown> =>
+  value !== null && typeof value === 'object' && !Array.isArray(value);
+
+/** Resolve and validate the email block from a loaded config (CLI/build side). An unusable block fails the build. */
+export const resolveEmailFromConfig = (config: ResolvedConfig | null | undefined): EmailSettings => {
+  const email = config?.runtime?.registry?.email as unknown as Record<string, unknown> | undefined;
+  const fail = (problem: string): never => {
+    throw new HandoffConfigError(`Config "runtime.registry.email": ${problem}`);
+  };
+
+  if (email === undefined) return { options: {} };
+  const provider = email.provider as EmailProviderKind;
+  if (!PROVIDERS.includes(provider)) {
+    fail(
+      email.provider === undefined
+        ? '"provider" is required. Use "smtp" or "custom".'
+        : `unknown provider ${JSON.stringify(provider)}. Use "smtp" or "custom".`
+    );
+  }
+  if (email.options !== undefined && !isPlainRecord(email.options)) {
+    fail('"options" must be an object.');
+  }
+  const options = { ...((email.options as Record<string, unknown> | undefined) ?? {}) };
+  const module = typeof email.module === 'string' ? email.module.trim() : undefined;
+
+  if (provider === 'custom') {
+    if (!module) fail('provider "custom" needs a "module" that default-exports a defineEmailProvider() result.');
+  } else {
+    if (email.module !== undefined) fail(`"module" is used only by provider "custom", not "${provider}".`);
+    const allowed = BUILT_IN_OPTIONS[provider];
+    const unknown = Object.keys(options).filter((key) => !allowed.includes(key));
+    if (unknown.length > 0) {
+      fail(
+        `provider "${provider}" does not support ${unknown.map((key) => `"options.${key}"`).join(', ')}. ` +
+          `Use ${allowed.map((key) => `"${key}"`).join(', ')}.`
+      );
+    }
+  }
+  if (provider === 'smtp' && options.host === undefined) fail('provider "smtp" needs "options.host".');
+
+  const from = typeof email.from === 'string' ? email.from.trim() || undefined : undefined;
+  return { from, provider, ...(module ? { module } : {}), options };
+};
+
+/** Read baked settings back leniently (server side): a malformed value must not take the server down. */
+export const parseEmailSettings = (raw: { from?: unknown; provider?: unknown; module?: unknown; options?: unknown }): EmailSettings => {
+  let options: unknown = raw.options;
+  if (typeof options === 'string') {
+    try {
+      options = options.trim() ? JSON.parse(options) : {};
+    } catch {
+      options = {};
+    }
+  }
+  const provider = PROVIDERS.find((kind) => kind === raw.provider);
+  const module = typeof raw.module === 'string' ? raw.module.trim() : '';
+  return {
+    from: typeof raw.from === 'string' ? raw.from.trim() || undefined : undefined,
+    ...(provider ? { provider } : {}),
+    ...(module ? { module } : {}),
+    options: isPlainRecord(options) ? options : {},
+  };
+};

package/src/registry/email/types.ts

@@ -0,0 +1,28 @@
+/**
+ * Server-only email provider contract. Handoff renders every message, and a provider only delivers it.
+ * SMTP is built in. Anything else is a {@link defineEmailProvider} module.
+ */
+
+/** One rendered message. */
+export interface EmailMessage {
+  from: string;
+  to: string;
+  subject: string;
+  html: string;
+  text: string;
+}
+
+/** The pluggable provider contract. `send` throws when the message is not accepted for delivery. */
+export interface EmailProvider {
+  send(message: EmailMessage): Promise<void>;
+}
+
+/** Context passed to a provider factory. */
+export interface EmailProviderContext {
+  /** `runtime.registry.email.options`, with environment references resolved to their values. */
+  options: Record<string, unknown>;
+  env: NodeJS.ProcessEnv;
+}
+
+/** A custom provider may export the provider directly or a factory that builds it from its context. */
+export type EmailProviderFactory = (context: EmailProviderContext) => EmailProvider | Promise<EmailProvider>;

package/src/registry/path.ts

@@ -13,6 +13,17 @@ export const isSafeRelativePath = (value: string): boolean => {
 
 export const normalizeRelativePath = (value: string): string => value.replace(/\\/g, '/');
 
+/** Unlike {@link isSafeRelativePath}, it can start with `../`. */
+export const isWorkspaceRelativePath = (value: unknown): value is string =>
+  typeof value === 'string' &&
+  value !== '' &&
+  value !== '.' &&
+  !value.includes('\0') &&
+  !value.includes('\\') &&
+  !value.startsWith('/') &&
+  !/^[a-zA-Z]:/.test(value) &&
+  path.posix.normalize(value) === value;
+
 export const isSafePathSegment = (value: string): boolean =>
   typeof value === 'string' && value === value.trim() && isSafeRelativePath(value) && !normalizeRelativePath(value).includes('/');
 

package/src/registry/publish/errors.ts

@@ -8,6 +8,10 @@ export const describeUploadFailure = (
   registryUrl: string,
   rejectedPayload: RejectedPublishPayload
 ): string => {
+  // An oversized body is rejected by the platform or body parser, so the response has no error envelope.
+  if (error.status === 413) {
+    return `The registry at ${registryUrl} rejected the ${rejectedPayload} as too large (413). Reduce the size of its largest files and publish again.`;
+  }
   switch (error.code) {
     case 'runtime_mode_conflict':
       return `The registry at ${registryUrl} is not running in registry mode, so it cannot accept publishes: ${error.message}`;

package/src/registry/publish/index.ts

@@ -21,7 +21,7 @@ import { loginCommandHint, resolveAuthenticatedRegistryConnection, unusedLoginNo
 import type { EntitySummary, TransferEntityKind } from '../transfer';
 import { quoteIds, selectIds, splitCatalogIds } from '../selection';
 import { describePublishError, describeUploadFailure } from './errors';
-import { assertRequiredArtifactsPresent, buildPublishPackage, PublishPackageError } from './package';
+import { assertPackageWithinUploadLimit, assertRequiredArtifactsPresent, buildPublishPackage, PublishPackageError } from './package';
 
 /** A connected-workspace configuration or precondition failure surfaced to the CLI. */
 export class PublishError extends Error {
@@ -173,6 +173,7 @@ export const publishEntity = async (handoff: Handoff, kind: TransferEntityKind,
 
   const pkg = await buildPublishPackage(handoff, kind, id);
   assertRequiredArtifactsPresent(pkg);
+  assertPackageWithinUploadLimit(kind, id, pkg);
 
   const contents = `${pkg.artifacts.length} artifact(s), ${pkg.files.length} source file(s)`;
   if (!client) {
@@ -274,6 +275,7 @@ const uploadEntities = async (handoff: Handoff, transport: PublishTransport, kin
     try {
       const pkg = await buildPublishPackage(handoff, kind, id);
       assertRequiredArtifactsPresent(pkg);
+      assertPackageWithinUploadLimit(kind, id, pkg);
 
       const remoteHash = remoteHashById.get(id);
       const localHash = entityHash(pkg.build);

package/src/registry/publish/package.ts

@@ -88,6 +88,13 @@ const enrichItem = async (
   return item;
 };
 
+const findSourceDir = async (handoff: Handoff, kind: RenderedEntityKind, id: string): Promise<string | undefined> => {
+  const runtime = kind === 'component' ? await handoff.store.components.get(id) : await handoff.store.patterns.get(id);
+  const sourceDir = (runtime as { path?: string } | null)?.path;
+  const relativeDir = sourceDir ? path.relative(handoff.workingPath, sourceDir) : '';
+  return relativeDir && !path.isAbsolute(relativeDir) ? relativeDir.split(path.sep).join('/') : undefined;
+};
+
 /** Map an entity's related source files to transfer files, dropping workspace-only declarations. */
 const collectSourceFiles = async (handoff: Handoff, kind: TransferEntityKind, id: string): Promise<TransferFile[]> => {
   const store = kind === 'component' ? handoff.store.components : kind === 'pattern' ? handoff.store.patterns : handoff.store.pages;
@@ -164,6 +171,7 @@ const buildComponentPackage = async (handoff: Handoff, id: string): Promise<Tran
   const artifacts = Array.from(byPath.values());
   return {
     item: await enrichItem(handoff, 'component', id, summary as unknown as Record<string, unknown>),
+    sourceDir: await findSourceDir(handoff, 'component', id),
     files: await collectSourceFiles(handoff, 'component', id),
     artifacts,
     build: createArtifactBuild(artifacts),
@@ -214,6 +222,7 @@ const buildPatternPackage = async (handoff: Handoff, id: string): Promise<Transf
   const artifacts = Array.from(byPath.values());
   return {
     item: await enrichItem(handoff, 'pattern', id, summary as unknown as Record<string, unknown>),
+    sourceDir: await findSourceDir(handoff, 'pattern', id),
     files: await collectSourceFiles(handoff, 'pattern', id),
     artifacts,
     build: createArtifactBuild(artifacts),
@@ -276,6 +285,30 @@ export const assertRequiredArtifactsPresent = (pkg: TransferPackage): void => {
   }
 };
 
+/**
+ * The largest publish request body the registry accepts. Vercel rejects a larger function body with
+ * `413 FUNCTION_PAYLOAD_TOO_LARGE`, and the transfer route's `bodyParser.sizeLimit` matches it.
+ */
+export const MAX_PUBLISH_BODY_BYTES = 4_500_000;
+
+const formatMegabytes = (bytes: number): string => `${(bytes / 1_000_000).toFixed(1)} MB`;
+
+export const assertPackageWithinUploadLimit = (kind: TransferEntityKind, id: string, pkg: TransferPackage): void => {
+  const size = Buffer.byteLength(JSON.stringify(pkg));
+  if (size <= MAX_PUBLISH_BODY_BYTES) return;
+
+  const largest = [...pkg.artifacts, ...pkg.files]
+    .map((entry) => ({ path: entry.path, size: Buffer.byteLength(entry.content) }))
+    .sort((a, b) => b.size - a.size)
+    .slice(0, 3)
+    .map((entry) => `  - ${entry.path} (${formatMegabytes(entry.size)})`)
+    .join('\n');
+  throw new PublishPackageError(
+    `The ${kind} "${id}" package is ${formatMegabytes(size)}; the registry accepts at most ` +
+      `${formatMegabytes(MAX_PUBLISH_BODY_BYTES)} per publish. Largest entries:\n${largest}`
+  );
+};
+
 /** Assemble the publish package for an entity from the generated `public/api` artifacts. */
 export const buildPublishPackage = (handoff: Handoff, kind: TransferEntityKind, id: string): Promise<TransferPackage> =>
   kind === 'component'

package/src/registry/transfer.ts

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

package/src/store/registry.ts

@@ -16,7 +16,7 @@
 
 import { orderPreviews } from '../catalog/previews';
 import { and, eq, inArray, or, sql, type SQLWrapper } from 'drizzle-orm';
-import type { AssetStorage, AssetStorageReadResult } from '../registry/asset-storage/types';
+import type { StorageProvider, StorageReadResult } from '../registry/asset-storage/types';
 import type { RegistryDatabase } from '../registry/db/client';
 import {
   assetBlobs,
@@ -53,11 +53,11 @@ import type {
 export interface RegistryStoreContext {
   db: RegistryDatabase;
   /**
-   * Resolve the {@link AssetStorage} adapter for a blob's recorded provider (or `null` for the inline
+   * Resolve the {@link StorageProvider} for a blob's recorded provider (or `null` for the inline
    * `database` provider). Injected by the app runtime so `src/store` stays free of app-side imports;
    * when omitted, only inline DB-backed asset content is resolvable.
    */
-  resolveAssetAdapter?: (provider: AssetStorageProvider) => Promise<AssetStorage | null>;
+  resolveStorageProvider?: (provider: AssetStorageProvider) => Promise<StorageProvider | null>;
 }
 
 /** A persisted text-file row, as selected from `component_files`/`pattern_files`. */
@@ -422,14 +422,14 @@ export class RegistryAssetStore implements AssetStore {
     }
 
     // Object-backed - resolve through the provider that stored it.
-    if (!row.storageRef || !this.context.resolveAssetAdapter) {
+    if (!row.storageRef || !this.context.resolveStorageProvider) {
       return null;
     }
-    const adapter = await this.context.resolveAssetAdapter(row.storageProvider);
-    if (!adapter) {
+    const storage = await this.context.resolveStorageProvider(row.storageProvider);
+    if (!storage) {
       return null;
     }
-    const result: AssetStorageReadResult = await adapter.get(row.storageRef);
+    const result: StorageReadResult = await storage.get(row.storageRef);
     if (result.kind === 'redirect') {
       return { ...base, redirectUrl: result.url };
     }

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

@@ -5,8 +5,10 @@ import type { SourceFormat } from '../../../catalog/renderers';
 import {
   BuildCache,
   checkOutputExists,
+  computeBuildInputStates,
   computeComponentFileStates,
   computeGlobalDepsState,
+  createBuildInputs,
   createEmptyCache,
   hasComponentChanged,
   haveGlobalDepsChanged,
@@ -162,27 +164,17 @@ const createComponentBuildPlan = (
   };
 };
 
-/**
- * Options for processing components
- */
-export interface ProcessComponentsOptions {
-  /** Enable caching to skip unchanged components */
-  useCache?: boolean;
-}
-
 /**
  * Process components and generate their code, styles, and previews
  * @param handoff - The Handoff instance containing configuration and state
  * @param id - Optional component ID to process a specific component
  * @param segmentToProcess - Optional segment to update
- * @param options - Optional processing options including cache settings
  * @returns Promise resolving to an array of processed components
  */
 export async function processComponents(
   handoff: Handoff,
   id?: string,
-  segmentToProcess?: ComponentSegment,
-  options?: ProcessComponentsOptions
+  segmentToProcess?: ComponentSegment
 ): Promise<ComponentListObject[]> {
   const result: ComponentListObject[] = [];
 
@@ -204,18 +196,17 @@ export async function processComponents(
     return [];
   }
 
-  // Determine which components need building based on cache (when enabled)
+  // Determine which components need building based on cache
   let componentsToBuild: Set<string>;
   let cache: BuildCache | null = null;
   let currentGlobalDeps = {};
   const componentFileStatesMap: Map<string, Awaited<ReturnType<typeof computeComponentFileStates>>> = new Map();
 
   // Only use caching when:
-  // - useCache option is enabled
   // - No specific component ID is requested (full build scenario)
   // - No specific segment is requested (full build scenario)
   // - Force flag is not set
-  const shouldUseCache = options?.useCache && !id && !segmentToProcess && !handoff.force;
+  const shouldUseCache = !id && !segmentToProcess && !handoff.force;
 
   if (shouldUseCache) {
     Logger.debug('Loading build cache...');
@@ -240,7 +231,7 @@ export async function processComponents(
         if (!cachedEntry) {
           Logger.info(`Component '${componentId}': new component, will build`);
           componentsToBuild.add(componentId);
-        } else if (hasComponentChanged(cachedEntry, currentFileStates)) {
+        } else if (await hasComponentChanged(cachedEntry, currentFileStates)) {
           Logger.info(`Component '${componentId}': source files changed, will rebuild`);
           componentsToBuild.add(componentId);
         } else if (!(await checkOutputExists(handoff, componentId))) {
@@ -372,6 +363,7 @@ export async function processComponents(
     // Components should always have at least one preview variation.
     ensureDefaultPreview(data);
 
+    const inputs = shouldUseCache ? createBuildInputs() : undefined;
     const runsViteBuildSteps = buildPlan.js || buildPlan.css || buildPlan.previews;
     let viteBuildStartedAtMs = 0;
     if (runsViteBuildSteps) {
@@ -381,11 +373,11 @@ export async function processComponents(
 
     // Build JS if needed (new build, validation missing, or explicit segment request).
     if (buildPlan.js) {
-      data = await buildComponentJs(data, handoff);
+      data = await buildComponentJs(data, handoff, inputs);
     }
     // Build CSS if needed.
     if (buildPlan.css) {
-      data = await buildComponentCss(data, handoff);
+      data = await buildComponentCss(data, handoff, inputs);
     }
     // Build previews (HTML, snapshots, etc) if needed.
     if (buildPlan.previews) {
@@ -395,7 +387,8 @@ export async function processComponents(
           previews: getBuildPreviews(data),
         },
         handoff,
-        components
+        components,
+        inputs
       );
     }
 
@@ -428,17 +421,18 @@ export async function processComponents(
     result.push(summary);
 
     // Update cache entry for this component after successful build
-    if (shouldUseCache) {
+    if (shouldUseCache && inputs) {
       if (!cache) {
         cache = createEmptyCache();
       }
-      const fileStates = componentFileStatesMap.get(runtimeComponentId);
-      if (fileStates) {
-        updateComponentCacheEntry(cache, runtimeComponentId, fileStates);
+      // Compute file states if not already computed (e.g., when global deps changed)
+      const fileStates = componentFileStatesMap.get(runtimeComponentId) ?? (await computeComponentFileStates(handoff, runtimeComponentId));
+      const inputStates = await computeBuildInputStates(handoff, runtimeComponentId, inputs);
+      if (inputStates) {
+        updateComponentCacheEntry(cache, runtimeComponentId, fileStates, inputStates);
       } else {
-        // Compute file states if not already computed (e.g., when global deps changed)
-        const computedFileStates = await computeComponentFileStates(handoff, runtimeComponentId);
-        updateComponentCacheEntry(cache, runtimeComponentId, computedFileStates);
+        // An incomplete list can miss a changed file, so the next run builds this component again.
+        delete cache.components[runtimeComponentId];
       }
     }
   }