handoff-app 2.0.0-8 → 2.0.0

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/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),

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/plugins/ssr-render.ts

@@ -25,7 +25,7 @@ import {
   type SharedArtifactPresence,
 } from '../preview/component/shared-artifacts';
 import { TransformComponentTokensResult } from '../preview/types';
-import { DEFAULT_CLIENT_BUILD_CONFIG, createReactResolvePlugin } from '../utils/build';
+import { DEFAULT_CLIENT_BUILD_CONFIG, createReactResolvePlugin, withStyleLoaders } from '../utils/build';
 import { formatHtml, trimPreview } from '../utils/html';
 import { buildAndEvaluateModule } from '../utils/module';
 import { loadSchemaFromComponent, loadSchemaFromFile } from '../utils/schema-loader';
@@ -138,13 +138,31 @@ async function loadComponentSchemaAndModule(
  * @param componentExport - Export holding the implementation; the default export when absent
  * @returns Client-side hydration source code
  */
-function generateClientHydrationSource(componentId: string, componentPath: string, componentExport?: string): string {
+function generateClientHydrationSource(
+  componentId: string,
+  componentPath: string,
+  componentExport?: string,
+  declarationPath?: string
+): string {
   const importClause = componentExport && componentExport !== 'default' ? `{ ${componentExport} as Component }` : 'Component';
+  // A function cannot travel in the JSON props, so the client re-reads `render` from the module that
+  // defines it. Conditional, so an unaffected component does not ship its declaration's imports.
+  const declarationImport = declarationPath ? `import * as previewDeclaration from '${normalizePath(declarationPath)}';` : '';
+  const resolveComponent = declarationPath
+    ? `(mount) => {
+      const previewKey = mount.getAttribute('data-handoff-preview');
+      const render = previewKey ? previewDeclaration[previewKey]?.render : undefined;
+      return typeof render === 'function' ? render : Component;
+    }`
+    : '() => Component';
 
   return `
     import React from 'react';
     import { hydrateRoot } from 'react-dom/client';
     import ${importClause} from '${normalizePath(componentPath)}';
+    ${declarationImport}
+
+    const resolveComponent = ${resolveComponent};
 
     const parseProps = (propsId) => {
       const raw = propsId ? document.getElementById(propsId)?.textContent : '{}';
@@ -157,12 +175,14 @@ function generateClientHydrationSource(componentId: string, componentPath: strin
 
     const standaloneRoot = document.getElementById('${PLUGIN_CONSTANTS.ROOT_ELEMENT_ID}');
     if (standaloneRoot && !standaloneRoot.hasAttribute('data-handoff-component')) {
-      hydrateRoot(standaloneRoot, <Component {...parseProps('${PLUGIN_CONSTANTS.PROPS_SCRIPT_ID}')} />);
+      const StandaloneComponent = resolveComponent(standaloneRoot);
+      hydrateRoot(standaloneRoot, <StandaloneComponent {...parseProps('${PLUGIN_CONSTANTS.PROPS_SCRIPT_ID}')} />);
     }
 
     const patternMounts = document.querySelectorAll('[data-handoff-component=' + JSON.stringify('${componentId}') + ']');
     patternMounts.forEach((mount) => {
-      hydrateRoot(mount, <Component {...parseProps(mount.getAttribute('data-handoff-props'))} />);
+      const MountComponent = resolveComponent(mount);
+      hydrateRoot(mount, <MountComponent {...parseProps(mount.getAttribute('data-handoff-props'))} />);
     });
   `;
 }
@@ -175,12 +195,13 @@ function generateClientHydrationSource(componentId: string, componentPath: strin
  * artifact cannot be loaded.
  * @param componentId - Component identifier
  * @param previewTitle - Title for the preview
- * @param renderedHtml - Server-rendered HTML content
+ * @param renderedHtml - Server-rendered HTML, embedded verbatim so the client can hydrate it
  * @param props - Component props as JSON
  * @returns Complete HTML document
  */
 function generateHtmlDocument(
   componentId: string,
+  previewKey: string,
   previewTitle: string,
   renderedHtml: string,
   props: any,
@@ -220,7 +241,7 @@ function generateHtmlDocument(
     <title>${previewTitle}</title>
   </head>
   <body>
-    <div id="${PLUGIN_CONSTANTS.ROOT_ELEMENT_ID}">${renderedHtml}</div>
+    <div id="${PLUGIN_CONSTANTS.ROOT_ELEMENT_ID}" data-handoff-preview="${previewKey}">${renderedHtml}</div>
   </body>
 </html>`;
 }
@@ -314,7 +335,15 @@ export function ssrRenderPlugin(
       // `component/<id>.client.js` artifact. The hydration source only imports the component and
       // reads props from the in-document `__APP_PROPS__` element, so it is identical across every
       // preview of this component.
-      const clientHydrationSource = generateClientHydrationSource(componentId, componentPath, componentData.componentExport);
+      const declarationPath = Object.values(componentData.previews ?? {}).some((preview) => typeof preview.render === 'function')
+        ? componentData.entries?.declaration
+        : undefined;
+      const clientHydrationSource = generateClientHydrationSource(
+        componentId,
+        componentPath,
+        componentData.componentExport,
+        declarationPath
+      );
       const clientBuildConfig = {
         ...DEFAULT_CLIENT_BUILD_CONFIG,
         logLevel: 'silent' as const,
@@ -326,9 +355,10 @@ export function ssrRenderPlugin(
         plugins: [createReactResolvePlugin(handoff.workingPath, handoff.modulePath)],
       };
 
-      const finalClientBuildConfig = handoff.config?.hooks?.clientBuildConfig
+      const hookedClientBuildConfig = handoff.config?.hooks?.clientBuildConfig
         ? handoff.config.hooks.clientBuildConfig(clientBuildConfig)
         : clientBuildConfig;
+      const finalClientBuildConfig = withStyleLoaders(hookedClientBuildConfig);
 
       let clientBundleJs: string;
       try {
@@ -364,16 +394,23 @@ export function ssrRenderPlugin(
 
       // Generate previews for each variation
       for (const previewKey in componentData.previews) {
-        const previewProps = componentData.previews[previewKey].values;
-
-        // Server-side render the component
-        const serverRenderedHtml = ReactDOMServer.renderToString(React.createElement(ReactComponent, previewProps));
-        const formattedHtml = await formatHtml(serverRenderedHtml);
+        const preview = componentData.previews[previewKey];
+        const previewProps = preview.values;
+        // A synthetic pattern preview is not a named export, so the client looks up its
+        // `sourcePreview` instead. A preview without one has no `render` either.
+        const hydrationPreviewKey = preview.sourcePreview ?? previewKey;
+        // Rendered as a component rather than called, so a preview can use hooks and own state.
+        const PreviewComponent = (typeof preview.render === 'function' ? preview.render : ReactComponent) as ReactComponent;
+
+        // The markup must reach the document exactly as rendered. Formatting it adds text nodes React
+        // does not expect, so it discards the server markup and re-renders the preview on the client.
+        const serverRenderedHtml = ReactDOMServer.renderToString(React.createElement(PreviewComponent, previewProps));
 
         finalHtml = generateHtmlDocument(
           componentId,
-          componentData.previews[previewKey].title,
-          formattedHtml,
+          hydrationPreviewKey,
+          preview.title,
+          serverRenderedHtml,
           previewProps,
           sharedArtifacts,
           componentArtifacts
@@ -402,7 +439,7 @@ export function ssrRenderPlugin(
         });
       }
 
-      // Format final HTML and update component data
+      // The previews are already emitted, so this formats only the docs code view.
       finalHtml = await formatHtml(finalHtml);
       componentData.format = 'react';
       componentData.preview = '';

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];
       }
     }
   }