handoff-app 1.2.0-0 → 1.2.0-2

package/src/app/pages/system/pattern/[pattern]/index.tsx

@@ -8,6 +8,9 @@ import Layout from '../../../../components/Layout/Main';
 import { MarkdownComponents } from '../../../../components/Markdown/MarkdownComponents';
 import PrevNextNav from '../../../../components/Navigation/PrevNextNav';
 import HeadersType from '../../../../components/Typography/Headers';
+import { Accordion, AccordionContent, AccordionItem, AccordionTrigger } from '../../../../components/ui/accordion';
+import { Badge } from '../../../../components/ui/badge';
+import { JsonTreeView } from '../../../../components/ui/json-tree-view';
 import {
   DocumentationProps,
   fetchPatterns,
@@ -25,6 +28,66 @@ interface PatternPageProps extends DocumentationProps {
   nextPattern: PatternNavItem | null;
 }
 
+const SYNTHETIC_PATTERN_PREVIEW_PREFIX = '__pattern_';
+
+const isSyntheticPatternPreview = (previewKey?: string) => Boolean(previewKey?.startsWith(SYNTHETIC_PATTERN_PREVIEW_PREFIX));
+
+const formatPreviewLabel = (component: PatternListObject['components'][number], index: number) => {
+  const previewKey = component.preview || component.resolvedPreview;
+
+  if (!previewKey) {
+    return {
+      title: 'Default preview',
+      subtitle: 'Uses the component default preview configuration.',
+      rawKey: null,
+    };
+  }
+
+  if (isSyntheticPatternPreview(previewKey)) {
+    return {
+      title: component.args ? 'Custom configuration' : `Generated preview ${index + 1}`,
+      subtitle: component.args ? 'Built from inline args for this pattern.' : 'Generated specifically for this pattern composition.',
+      rawKey: previewKey,
+    };
+  }
+
+  return {
+    title: startCase(previewKey),
+    subtitle: 'Named preview from the component docs.',
+    rawKey: previewKey,
+  };
+};
+
+const formatArgValue = (value: unknown) => {
+  if (typeof value === 'string') {
+    return value.length > 24 ? `${value.slice(0, 21)}...` : value;
+  }
+
+  if (typeof value === 'number' || typeof value === 'boolean') {
+    return String(value);
+  }
+
+  if (Array.isArray(value)) {
+    return `${value.length} item${value.length === 1 ? '' : 's'}`;
+  }
+
+  if (value && typeof value === 'object') {
+    return `${Object.keys(value as Record<string, unknown>).length} fields`;
+  }
+
+  if (value === null) {
+    return 'null';
+  }
+
+  return 'set';
+};
+
+const getArgSummary = (args?: Record<string, unknown>) => {
+  if (!args) return [];
+
+  return Object.entries(args).slice(0, 3);
+};
+
 export async function getStaticPaths() {
   return {
     paths: fetchPatterns()?.map((p) => ({ params: { pattern: p.id } })) ?? [],
@@ -74,12 +137,8 @@ const PatternPage = ({ menu, metadata, current, id, config, previousPattern, nex
   const normalizedBasePath = appBasePath ? `/${appBasePath.replace(/^\/+|\/+$/g, '')}` : '';
   const patternRoute = (patternId: string) => `${normalizedBasePath}/system/pattern/${patternId}`;
 
-  const previousLink = previousPattern
-    ? { href: patternRoute(previousPattern.id), title: previousPattern.title }
-    : null;
-  const nextLink = nextPattern
-    ? { href: patternRoute(nextPattern.id), title: nextPattern.title }
-    : null;
+  const previousLink = previousPattern ? { href: patternRoute(previousPattern.id), title: previousPattern.title } : null;
+  const nextLink = nextPattern ? { href: patternRoute(nextPattern.id), title: nextPattern.title } : null;
   const invalidComponents = pattern?.components?.filter((comp) => comp.resolved === false) ?? [];
 
   useEffect(() => {
@@ -115,7 +174,15 @@ const PatternPage = ({ menu, metadata, current, id, config, previousPattern, nex
     <Layout config={config} menu={menu} current={current} metadata={metadata}>
       <div className="flex flex-col gap-3 pb-14">
         <small className="text-sm font-medium text-sky-600 dark:text-gray-300">Patterns</small>
-        <HeadersType.H1>{metadata.title}</HeadersType.H1>
+        <div className="flex flex-wrap items-center gap-3">
+          <HeadersType.H1>{metadata.title}</HeadersType.H1>
+          <Badge
+            variant="outline"
+            className="rounded-full border border-gray-200 px-3 py-1 text-[11px] font-medium text-gray-600 dark:border-gray-700 dark:text-gray-300"
+          >
+            {pattern.components?.length ?? 0} component{(pattern.components?.length ?? 0) === 1 ? '' : 's'}
+          </Badge>
+        </div>
         {metadata.description && (
           <div className="prose max-w-[800px] text-xl font-light leading-relaxed text-gray-600 dark:text-gray-300">
             <ReactMarkdown components={MarkdownComponents} rehypePlugins={[rehypeRaw]}>
@@ -126,20 +193,10 @@ const PatternPage = ({ menu, metadata, current, id, config, previousPattern, nex
       </div>
 
       <div className="max-w-[1100px]">
-        {/* Pattern composition info */}
-        <div className="mb-4 flex items-center gap-2 text-sm text-gray-500">
-          <span>{pattern.components?.length ?? 0} component(s)</span>
-          {pattern.group && (
-            <>
-              <span className="text-gray-300">|</span>
-              <span>{pattern.group}</span>
-            </>
-          )}
-        </div>
-
         {invalidComponents.length > 0 && (
           <div className="mb-4 rounded-lg border border-amber-300 bg-amber-50 px-4 py-3 text-sm text-amber-900 dark:border-amber-800 dark:bg-amber-950/40 dark:text-amber-200">
-            {invalidComponents.length} pattern component{invalidComponents.length > 1 ? 's could' : ' could'} not be resolved and {invalidComponents.length > 1 ? 'were' : 'was'} skipped.
+            {invalidComponents.length} pattern component{invalidComponents.length > 1 ? 's could' : ' could'} not be resolved and{' '}
+            {invalidComponents.length > 1 ? 'were' : 'was'} skipped.
           </div>
         )}
 
@@ -163,9 +220,7 @@ const PatternPage = ({ menu, metadata, current, id, config, previousPattern, nex
                 src={`${normalizedBasePath}/api/pattern/${pattern.url}`}
               />
             ) : (
-              <div className="flex items-center justify-center p-8 text-sm text-gray-500">
-                No preview available for this pattern.
-              </div>
+              <div className="flex items-center justify-center p-8 text-sm text-gray-500">No preview available for this pattern.</div>
             )}
           </div>
         </div>
@@ -173,42 +228,110 @@ const PatternPage = ({ menu, metadata, current, id, config, previousPattern, nex
         {/* Component list */}
         {pattern.components && pattern.components.length > 0 && (
           <div className="mt-8">
-            <HeadersType.H3>Components in this pattern</HeadersType.H3>
-            <div className="mt-4 overflow-hidden rounded-lg border border-gray-200 dark:border-gray-800">
-              <table className="w-full text-sm">
-                <thead className="border-b bg-gray-50 dark:bg-gray-800">
-                  <tr>
-                    <th className="px-4 py-2 text-left font-medium text-gray-600 dark:text-gray-300">Component</th>
-                    <th className="px-4 py-2 text-left font-medium text-gray-600 dark:text-gray-300">Preview</th>
-                    <th className="px-4 py-2 text-left font-medium text-gray-600 dark:text-gray-300">Status</th>
-                    <th className="px-4 py-2 text-left font-medium text-gray-600 dark:text-gray-300">Custom Args</th>
-                  </tr>
-                </thead>
-                <tbody>
-                  {pattern.components.map((comp, i) => (
-                    <tr key={`${comp.id}-${i}`} className="border-b last:border-b-0 dark:border-gray-800">
-                      <td className="px-4 py-2 font-mono text-xs">{comp.id}</td>
-                      <td className="px-4 py-2 text-xs text-gray-500">
-                        {comp.preview || comp.resolvedPreview || 'default'}
-                      </td>
-                      <td className="px-4 py-2 text-xs">
-                        {comp.resolved === false ? (
-                          <span className="inline-flex w-fit rounded-full bg-amber-100 px-2 py-0.5 text-[11px] font-medium text-amber-800 dark:bg-amber-900/60 dark:text-amber-200">
+            <div className="flex flex-col gap-2 md:flex-row md:items-end md:justify-between">
+              <div>
+                <HeadersType.H3>Components in this pattern</HeadersType.H3>
+              </div>
+            </div>
+
+            <div className="mt-5 overflow-hidden rounded-xl border border-gray-200 dark:border-gray-800">
+              {pattern.components.map((comp, i) => {
+                const previewMeta = formatPreviewLabel(comp, i);
+                const argSummary = getArgSummary(comp.args);
+                const hasArgs = Boolean(comp.args);
+
+                return (
+                  <div
+                    key={`${comp.id}-${i}`}
+                    className="border-b border-gray-200 bg-white last:border-b-0 dark:border-gray-800 dark:bg-transparent"
+                  >
+                    <div className="grid gap-4 px-5 py-4 md:grid-cols-[minmax(0,220px)_minmax(0,1fr)] md:px-6">
+                      <div className="flex flex-wrap items-center gap-3">
+                        <span className="text-xs font-medium text-gray-400 dark:text-gray-500">{String(i + 1).padStart(2, '0')}</span>
+                        <code className="font-mono text-[13px] text-gray-900 dark:text-gray-100">{comp.id}</code>
+                        {comp.resolved === false && (
+                          <Badge variant="warning" className="rounded-full px-2.5 py-0.5 text-[11px] font-medium">
                             Unresolved
-                          </span>
+                          </Badge>
+                        )}
+                      </div>
+
+                      <div className="min-w-0">
+                        {comp.resolved === false ? (
+                          <div className="rounded-md bg-amber-50 px-3 py-2 text-sm text-amber-900 dark:bg-amber-950/40 dark:text-amber-200">
+                            Could not resolve component preview.
+                          </div>
                         ) : (
-                          <span className="inline-flex w-fit rounded-full bg-emerald-100 px-2 py-0.5 text-[11px] font-medium text-emerald-800 dark:bg-emerald-900/60 dark:text-emerald-200">
-                            OK
-                          </span>
+                          <>
+                            <div className="space-y-2">
+                              <div>
+                                <p className="text-[10px] font-medium uppercase tracking-[0.1em] text-gray-400 dark:text-gray-500">
+                                  Preview
+                                </p>
+                                <p className="mt-1 text-sm font-medium text-gray-900 dark:text-gray-100">{previewMeta.title}</p>
+                              </div>
+
+                              {previewMeta.rawKey && !hasArgs && (
+                                <div className="inline-flex max-w-full items-center gap-2 rounded-md bg-gray-50 px-2.5 py-1.5 dark:bg-gray-900">
+                                  <span className="text-[10px] font-medium uppercase tracking-[0.12em] text-gray-400 dark:text-gray-500">
+                                    Key
+                                  </span>
+                                  <code className="truncate font-mono text-xs text-gray-500 dark:text-gray-400">{previewMeta.rawKey}</code>
+                                </div>
+                              )}
+                            </div>
+
+                            {hasArgs ? (
+                              <div className="mt-2">
+                                <Accordion type="single" collapsible className="mt-1">
+                                  <AccordionItem value={`args-${i}`} className="border-none">
+                                    <div className="flex flex-wrap gap-2">
+                                      {argSummary.length > 0 && (
+                                        <dl className="flex flex-wrap gap-2">
+                                          {argSummary.map(([key, value]) => (
+                                            <div
+                                              key={key}
+                                              className="inline-flex max-w-full items-center gap-2 rounded-md bg-gray-50 px-2.5 py-1.5 dark:bg-gray-900"
+                                            >
+                                              <dt className="text-[10px] font-medium uppercase tracking-[0.12em] text-gray-400 dark:text-gray-500">
+                                                {key}
+                                              </dt>
+                                              <dd className="truncate text-xs text-gray-900 dark:text-gray-100">{formatArgValue(value)}</dd>
+                                            </div>
+                                          ))}
+                                          {Object.keys(comp.args ?? {}).length > argSummary.length && (
+                                            <div className="inline-flex max-w-full items-center rounded-md bg-gray-50 px-2.5 py-1.5 text-xs text-gray-500 dark:bg-gray-900 dark:text-gray-400">
+                                              +{Object.keys(comp.args ?? {}).length - argSummary.length} more
+                                            </div>
+                                          )}
+                                        </dl>
+                                      )}
+
+                                      <AccordionTrigger className="inline-flex w-auto flex-none items-center gap-1 rounded-md bg-gray-50 px-2.5 py-1.5 text-[10px] font-medium uppercase tracking-[0.12em] text-gray-400 no-underline hover:bg-gray-100 hover:text-gray-600 hover:no-underline dark:bg-gray-900 dark:text-gray-500 dark:hover:bg-gray-800 dark:hover:text-gray-300 [&>svg]:h-3.5 [&>svg]:w-3.5">
+                                        All args
+                                      </AccordionTrigger>
+                                    </div>
+                                    <AccordionContent className="pt-2">
+                                      <JsonTreeView
+                                        data={comp.args}
+                                        defaultExpanded
+                                        maxInitialDepth={1}
+                                        className="rounded-lg border border-gray-200 bg-gray-50 p-3 dark:border-gray-800 dark:bg-gray-900"
+                                      />
+                                    </AccordionContent>
+                                  </AccordionItem>
+                                </Accordion>
+                              </div>
+                            ) : (
+                              <></>
+                            )}
+                          </>
                         )}
-                      </td>
-                      <td className="px-4 py-2 text-xs text-gray-500">
-                        {comp.args ? JSON.stringify(comp.args) : '-'}
-                      </td>
-                    </tr>
-                  ))}
-                </tbody>
-              </table>
+                      </div>
+                    </div>
+                  </div>
+                );
+              })}
             </div>
           </div>
         )}

package/src/app-builder/build.ts

@@ -105,13 +105,16 @@ const buildApp = async (handoff: Handoff, skipComponents?: boolean): Promise<voi
   // Build app
   const buildResult = spawn.sync('npx', ['next', 'build'], {
     cwd: appPath,
-    stdio: 'inherit',
+    stdio: ['inherit', 'pipe', 'pipe'],
     env: {
       ...process.env,
       NODE_ENV: 'production',
     },
   });
 
+  Logger.childProcessBuffer(buildResult.stdout);
+  Logger.childProcessBuffer(buildResult.stderr);
+
   if (buildResult.status !== 0) {
     let errorMsg = `Next.js build failed with exit code ${buildResult.status}`;
     if (buildResult.error) {
@@ -166,24 +169,32 @@ export const watchApp = async (handoff: Handoff): Promise<void> => {
     // create empty directory
     await fs.ensureDir(moduleOutput);
   }
+  Logger.info(`Starting Next.js dev server (Turbopack) at http://${hostname}:${port}…`);
+
   const nextProcess = spawn('npx', ['next', 'dev', '--turbopack', '--port', String(port)], {
     cwd: appPath,
-    stdio: 'inherit',
+    stdio: ['inherit', 'pipe', 'pipe'],
     env: {
       ...process.env,
       NODE_ENV: 'development',
     },
   });
-  Logger.success(`Ready on http://${hostname}:${port}`);
+  Logger.pipeChildStreams(nextProcess.stdout, nextProcess.stderr);
 
   nextProcess.on('error', (error) => {
-    Logger.error(`Next.js dev process error: ${error}`);
+    Logger.error(`Next.js dev process failed to start: ${error}`);
     process.exit(1);
   });
 
-  nextProcess.on('close', (code) => {
-    Logger.success(`Next.js dev process closed with code ${code}`);
-    process.exit(code);
+  nextProcess.on('close', (code, signal) => {
+    if (code === 0) {
+      Logger.success(`Next.js dev process exited normally`);
+    } else if (signal) {
+      Logger.warn(`Next.js dev process stopped (${signal})`);
+    } else {
+      Logger.error(`Next.js dev process exited with code ${code}`);
+    }
+    process.exit(code ?? 1);
   });
 
   const wss = await createWebSocketServer(handoff.config.app.ports?.websocket ?? 3001);
@@ -227,16 +238,21 @@ export const devApp = async (handoff: Handoff): Promise<void> => {
   // Persist client configuration
   await persistClientConfig(handoff);
 
-  // Run
-  const devResult = spawn.sync('npx', ['next', 'dev', '--turbopack', '--port', String(handoff.config.app.ports?.app ?? 3000)], {
+  const devPort = handoff.config.app.ports?.app ?? 3000;
+  Logger.info(`Starting Next.js dev server (Turbopack) on port ${devPort}…`);
+
+  const devResult = spawn.sync('npx', ['next', 'dev', '--turbopack', '--port', String(devPort)], {
     cwd: appPath,
-    stdio: 'inherit',
+    stdio: ['inherit', 'pipe', 'pipe'],
     env: {
       ...process.env,
       NODE_ENV: 'development',
     },
   });
 
+  Logger.childProcessBuffer(devResult.stdout);
+  Logger.childProcessBuffer(devResult.stderr);
+
   if (devResult.status !== 0) {
     let errorMsg = `Next.js dev failed with exit code ${devResult.status}`;
     if (devResult.error) {

package/src/app-builder/config-diff/index.ts

@@ -1,4 +1,4 @@
-export type { ConfigDiffStrategy, RebuildHandle } from './types';
+export type { ConfigDiffStrategy, FinalizeContext, RebuildHandle } from './types';
 export { type MapSnapshot, diffMapSnapshots, stableStringify } from './snapshot';
 export { patternDiffStrategy } from './strategies/pattern';
 export { getAllStrategies, getStrategy, runAllFinalizers } from './registry';

package/src/app-builder/config-diff/registry.ts

@@ -1,6 +1,6 @@
 import Handoff from '../..';
 import { patternDiffStrategy } from './strategies/pattern';
-import { ConfigDiffStrategy } from './types';
+import { ConfigDiffStrategy, FinalizeContext } from './types';
 
 const strategies = new Map<string, ConfigDiffStrategy>([
   [patternDiffStrategy.kind, patternDiffStrategy],
@@ -16,8 +16,8 @@ export const getAllStrategies = (): ConfigDiffStrategy[] =>
  * Runs every registered strategy finalizer.
  * Called after component rebuilds so derived artifacts stay up-to-date.
  */
-export const runAllFinalizers = async (handoff: Handoff): Promise<void> => {
+export const runAllFinalizers = async (handoff: Handoff, context?: FinalizeContext): Promise<void> => {
   for (const strategy of strategies.values()) {
-    await strategy.finalize(handoff);
+    await strategy.finalize(handoff, context);
   }
 };

package/src/app-builder/config-diff/strategies/pattern.ts

@@ -1,9 +1,10 @@
 import Handoff from '../../..';
 import { buildPatterns } from '../../../pipeline/patterns';
 import processComponents, { ComponentSegment } from '../../../transformers/preview/component/builder';
+import { getPatternIdsReferencingComponents } from '../../../transformers/preview/pattern/builder';
 import { Logger } from '../../../utils/logger';
 import { diffMapSnapshots, MapSnapshot, stableStringify } from '../snapshot';
-import { ConfigDiffStrategy } from '../types';
+import { ConfigDiffStrategy, FinalizeContext } from '../types';
 
 /**
  * Snapshots every __pattern_{patternId}_* synthetic preview entry across all
@@ -59,7 +60,21 @@ export const patternDiffStrategy: ConfigDiffStrategy = {
     };
   },
 
-  async finalize(handoff) {
+  async finalize(handoff, context?: FinalizeContext) {
+    if (context?.skipPatternFinalizer) {
+      return;
+    }
+
+    const componentIds = context?.patternRebuildComponentIds;
+    if (componentIds?.length) {
+      const patternIds = getPatternIdsReferencingComponents(handoff, componentIds);
+      if (patternIds.length === 0) {
+        return;
+      }
+      await buildPatterns(handoff, { onlyPatternIds: new Set(patternIds) });
+      return;
+    }
+
     await buildPatterns(handoff);
   },
 };

package/src/app-builder/config-diff/types.ts

@@ -1,5 +1,20 @@
 import Handoff from '../..';
 
+/**
+ * Optional hints for post-build finalizers (e.g. selective pattern rebuild).
+ */
+export type FinalizeContext = {
+  /**
+   * Only patterns that reference at least one of these component ids are rebuilt.
+   * When omitted, all patterns are rebuilt.
+   */
+  patternRebuildComponentIds?: string[];
+  /**
+   * When true, skip pattern artifact generation (no component preview HTML changed).
+   */
+  skipPatternFinalizer?: boolean;
+};
+
 /**
  * Handle returned by ConfigDiffStrategy.capture().
  *
@@ -17,5 +32,5 @@ export interface RebuildHandle {
 export interface ConfigDiffStrategy {
   readonly kind: string;
   capture(handoff: Handoff, entityId: string): RebuildHandle;
-  finalize(handoff: Handoff): Promise<void>;
+  finalize(handoff: Handoff, context?: FinalizeContext): Promise<void>;
 }

package/src/app-builder/paths.ts

@@ -30,6 +30,17 @@ export const getAppPath = (handoff: Handoff): string => {
   return path.resolve(handoff.modulePath, '.handoff', `${handoff.getProjectId()}`);
 };
 
+const mirrorDirectory = async (sourcePath: string, destinationPath: string): Promise<void> => {
+  if (!(await fs.pathExists(sourcePath))) {
+    await fs.remove(destinationPath);
+    return;
+  }
+
+  await fs.remove(destinationPath);
+  await fs.ensureDir(path.dirname(destinationPath));
+  await fs.copy(sourcePath, destinationPath, { overwrite: true });
+};
+
 /**
  * Copy the public dir from the working dir to the module dir.
  */
@@ -37,8 +48,18 @@ export const syncPublicFiles = async (handoff: Handoff): Promise<void> => {
   const appPath = getAppPath(handoff);
   const workingPublicPath = getWorkingPublicPath(handoff);
   if (workingPublicPath) {
-    await fs.copy(workingPublicPath, path.resolve(appPath, 'public'), {
+    const destinationPublicPath = path.resolve(appPath, 'public');
+    const sourceApiPath = path.resolve(workingPublicPath, 'api');
+    const destinationApiPath = path.resolve(destinationPublicPath, 'api');
+
+    await fs.copy(workingPublicPath, destinationPublicPath, {
       overwrite: true,
+      filter: (file) => {
+        const relativePath = path.relative(workingPublicPath, file);
+        return relativePath !== 'api' && !relativePath.startsWith(`api${path.sep}`);
+      },
     });
+
+    await mirrorDirectory(sourceApiPath, destinationApiPath);
   }
 };

package/src/app-builder/watchers.ts

@@ -8,7 +8,7 @@ import { buildMainJS } from '../transformers/preview/component/javascript';
 import { Logger } from '../utils/logger';
 import { isPathInside, normalizePathForCompare } from '../utils/path';
 import { persistClientConfig } from './client-config';
-import { getStrategy, runAllFinalizers } from './config-diff';
+import { getStrategy, runAllFinalizers, type FinalizeContext } from './config-diff';
 import { syncPublicFiles } from './paths';
 import {
   getRuntimeComponentsPathsToWatch,
@@ -185,8 +185,20 @@ export const watchRuntimeComponents = (
               const entryType = runtimeComponentEntryTypeByPath.get(normalizedFile);
               const segmentToUpdate: ComponentSegment | undefined = entryType ? mapEntryTypeToSegment(entryType) : undefined;
               const componentId = resolveComponentIdForChangedFile(handoff, file);
+
+              const skipPatterns =
+                segmentToUpdate === ComponentSegment.JavaScript ||
+                segmentToUpdate === ComponentSegment.Style;
+
+              let finalizeContext: FinalizeContext | undefined;
+              if (skipPatterns) {
+                finalizeContext = { skipPatternFinalizer: true };
+              } else if (componentId) {
+                finalizeContext = { patternRebuildComponentIds: [componentId] };
+              }
+
               await processComponents(handoff, componentId, segmentToUpdate);
-              await runAllFinalizers(handoff);
+              await runAllFinalizers(handoff, finalizeContext);
             } catch (e) {
               Logger.error('Error processing component:', e);
             }
@@ -314,7 +326,7 @@ export const watchComponentDirectories = (handoff: Handoff, state: WatcherState,
         watchRuntimeComponents(handoff, state, getRuntimeComponentsPathsToWatch(handoff));
         watchRuntimeConfiguration(handoff, state);
         await processComponents(handoff, dirName);
-        await runAllFinalizers(handoff);
+        await runAllFinalizers(handoff, { patternRebuildComponentIds: [dirName] });
       } catch (e) {
         Logger.error('Error processing new component:', e);
       }

package/src/app-builder/websocket.ts

@@ -13,8 +13,21 @@ export interface HandoffWebSocket extends WebSocket {
  * @returns A function that accepts a message string and broadcasts it to all connected clients.
  */
 export const createWebSocketServer = async (port: number = 3001) => {
+  Logger.info(`Starting WebSocket server for live reload on port ${port}…`);
+
   const wss = new WebSocket.Server({ port });
 
+  wss.on('listening', () => {
+    Logger.info(`WebSocket server listening on ws://localhost:${port} (live reload)`);
+  });
+
+  wss.on('error', (err) => {
+    Logger.error(
+      `WebSocket server failed${err instanceof Error ? `: ${err.message}` : ''}`,
+      err instanceof Error ? err : undefined
+    );
+  });
+
   // Heartbeat function to mark a connection as alive.
   const heartbeat = function (this: HandoffWebSocket) {
     this.isAlive = true;
@@ -25,7 +38,7 @@ export const createWebSocketServer = async (port: number = 3001) => {
     const extWs = ws as HandoffWebSocket;
     extWs.isAlive = true;
     extWs.send(JSON.stringify({ type: 'WELCOME' }));
-    extWs.on('error', (error) => Logger.error('WebSocket error:', error));
+    extWs.on('error', (error) => Logger.error('WebSocket client error:', error));
     extWs.on('pong', heartbeat);
   });
 
@@ -34,7 +47,7 @@ export const createWebSocketServer = async (port: number = 3001) => {
     wss.clients.forEach((client) => {
       const extWs = client as HandoffWebSocket;
       if (!extWs.isAlive) {
-        Logger.warn('Terminating inactive client');
+        Logger.debug('Terminating inactive WebSocket client');
         return client.terminate();
       }
       extWs.isAlive = false;
@@ -47,11 +60,9 @@ export const createWebSocketServer = async (port: number = 3001) => {
     clearInterval(pingInterval);
   });
 
-  Logger.success(`WebSocket server listening on ws://localhost:${port}`);
-
   // Return a function to broadcast a message to all connected clients
   return (message: string) => {
-    Logger.success(`Broadcasting message to ${wss.clients.size} client(s)`);
+    Logger.debug(`Broadcasting reload to ${wss.clients.size} WebSocket client(s)`);
     wss.clients.forEach((client) => {
       if (client.readyState === WebSocket.OPEN) {
         client.send(message);

package/src/cli.ts

@@ -19,7 +19,7 @@ class HandoffCliError extends Error {
  * Show the help message
  */
 const showVersion = () => {
-  return 'Handoff App - 1.2.0-0';
+  return 'Handoff App - 1.2.0-2';
 };
 
 /**

package/src/config/normalizers/pattern.ts

@@ -5,7 +5,6 @@ type RawPatternDeclaration = Record<string, any>;
 type NormalizePatternOptions = {
   declarationPath: string;
   fallbackId: string;
-  warn: (message: string) => void;
 };
 
 export const normalizePatternDeclaration = (
@@ -33,12 +32,6 @@ export const normalizePatternDeclaration = (
 
     const preview = typeof ref.preview === 'string' ? ref.preview.trim() : undefined;
 
-    if (!preview && !ref.args) {
-      options.warn(
-        `Pattern "${options.fallbackId}" component ref "${ref.id}" at index ${index} has neither "preview" nor "args". The component's default preview will be used.`
-      );
-    }
-
     return {
       id: ref.id.trim(),
       preview,

package/src/config/runtime.ts

@@ -282,7 +282,6 @@ export const initRuntimeConfig = (handoff: HandoffContext): [runtimeConfig: Runt
         pattern = normalizePatternDeclaration(rawPattern, {
           declarationPath: resolvedPatternConfigPath,
           fallbackId: patternBaseName,
-          warn: (message) => Logger.warn(message),
         });
       } catch (err) {
         Logger.error(`Failed to read or parse pattern config: ${resolvedPatternConfigPath}`, err);
@@ -387,11 +386,19 @@ const injectPatternPreviews = (result: RuntimeConfig): void => {
         continue;
       }
 
-      // Case 2: no preview AND no args -> use the component's first existing preview
+      // Case 2: no preview AND no args -> use the component's first existing preview (never assume "default")
       if (!ref.preview && !ref.args) {
         const previewKeys = Object.keys(component.previews || {});
-        ref.resolvedPreview = previewKeys[0] || 'default';
-        ref.resolved = true;
+        const firstPreview = previewKeys[0];
+        if (firstPreview) {
+          ref.resolvedPreview = firstPreview;
+          ref.resolved = true;
+        } else {
+          Logger.warn(
+            `Pattern "${patternId}" component ref "${ref.id}" has neither "preview" nor "args", and the component has no previews. This fragment will be skipped.`
+          );
+          ref.resolved = false;
+        }
         continue;
       }