handoff-app 1.2.2-7 → 2.0.0-0

package/src/app-builder/vercel-output.ts

@@ -0,0 +1,297 @@
+import fs from 'fs-extra';
+import path from 'path';
+import Handoff from '..';
+import { Logger } from '../utils/logger';
+
+/**
+ * Vercel Build Output API layout.
+ *
+ * `--package vercel` emits the Vercel Build Output API directory (`.vercel/output`) instead of the
+ * sites-directory deliverable. This module is the single seam that produces that layout; it is
+ * invoked as the final-assembly branch from the build functions and never re-stages or re-runs Next.
+ *
+ * Hard constraint: `.vercel/output` must live at the **repo root** (`handoff.workingPath`) with that
+ * exact name. Vercel ignores any `sitesOutputDirectory`-style override for this packaging.
+ */
+
+/** Build Output API config version emitted in `.vercel/output/config.json`. */
+const BUILD_OUTPUT_API_VERSION = 3;
+
+/** Absolute path of the `.vercel/output` directory at the repo root. */
+export const getVercelOutputPath = (handoff: Handoff): string => path.resolve(handoff.workingPath, '.vercel', 'output');
+
+/**
+ * Resolve the app base path exactly as `next.config.mjs`'s `resolveBasePath` does, so the emitted
+ * `config.json` reflects the same `basePath` the static export was built with. Empty string means no
+ * base path (the Build Output API omits the field rather than carrying an empty value).
+ */
+const resolveBasePath = (rawBasePath: string | undefined): string => {
+  if (!rawBasePath) {
+    return '';
+  }
+  const trimmed = rawBasePath.replace(/^\/+|\/+$/g, '');
+  return trimmed ? `/${trimmed}` : '';
+};
+
+/**
+ * Lay a materialized static export under `.vercel/output/static/` and write a minimal Build Output
+ * API v3 `config.json` carrying the app's `trailingSlash` and resolved `basePath`. Pure CDN files —
+ * no functions, no database.
+ *
+ * @param exportDir Absolute path of the materialized static export (the same content the static
+ *   target writes to `out/<projectId>`).
+ */
+export const writeStaticVercelOutput = async (handoff: Handoff, exportDir: string): Promise<void> => {
+  const outputPath = getVercelOutputPath(handoff);
+  await fs.remove(outputPath);
+  await fs.ensureDir(outputPath);
+
+  // Lay the export under static/ — pure CDN files, served directly by Vercel.
+  const staticDir = path.join(outputPath, 'static');
+  await fs.copy(exportDir, staticDir, { overwrite: true });
+
+  // The staged Next app sets `trailingSlash: true` (src/app/next.config.mjs); the registry/static
+  // exports inherit it. Carry it and the resolved base path so the static deploy serves correct URLs.
+  const basePath = resolveBasePath(handoff.config?.app?.base_path);
+  const config: { version: number; trailingSlash: boolean; basePath?: string } = {
+    version: BUILD_OUTPUT_API_VERSION,
+    trailingSlash: true,
+  };
+  if (basePath) {
+    config.basePath = basePath;
+  }
+  await fs.writeFile(path.join(outputPath, 'config.json'), `${JSON.stringify(config, null, 2)}\n`);
+
+  Logger.success(`Packaged static Vercel Build Output API artifact at ${outputPath} (static/ + config.json).`);
+};
+
+/**
+ * Node.js runtime identifier baked into the registry function's `.vc-config.json`. The `pg` adapter
+ * (and the Neon serverless driver in its Node fallback) need the Node.js runtime, not the edge
+ * runtime — this is the required baseline. Vercel resolves the patch
+ * version within this major; pinning the major keeps the artifact stable.
+ */
+const VERCEL_NODE_RUNTIME = 'nodejs20.x';
+
+/** Name (sans `.func`) of the single registry function. Served at `/` and the catch-all route. */
+const REGISTRY_FUNCTION_NAME = 'index';
+
+/** Handler file the Node launcher executes; wraps the Next standalone server as a request listener. */
+const REGISTRY_FUNCTION_HANDLER = 'index.js';
+
+/** Catch-all docs pages may be overridden by registry records and must always reach the function. */
+const MUTABLE_REGISTRY_PAGE_SRC_ROUTE = '/[...slug]';
+
+/**
+ * Node launcher emitted into the registry function directory. The Next `standalone` `server.js`
+ * binds a port via `startServer`, which is not the Vercel Node function contract (a module exporting
+ * a `(req, res)` request listener). This launcher reuses the exact same request pipeline that
+ * `startServer` boots — the router-server handler from `next/dist/server/lib/start-server` — but
+ * without the port bind, so it serves requests identically to `node server.js`.
+ *
+ * Why not the public `next().getRequestHandler()`: that handler resolves page/document and `/api`
+ * routes, but does NOT resolve on-demand `/_next/data/<buildId>/…json` requests for
+ * `fallback:'blocking'` pages — it 404s them. That broke client-side `<Link>` navigation to the
+ * component/pattern detail pages (their data fetch went to the function and came back 404, which the
+ * Next router then turns into a hard navigation). `getRequestHandlers` returns the full router-server
+ * handler (data-route resolution, dynamic param extraction, `trailingSlash` redirects), so on-demand
+ * data routes resolve the same way they do under the standalone server. `minimalMode:false` keeps
+ * the function doing full in-process routing (the catch-all route forwards everything here).
+ *
+ * Runtime mode, adapter, and the DB env-var *name* are already baked into the resolved config the
+ * standalone build wrote to `.next/required-server-files.json`; the connection-string value is still
+ * read from the named env var at request time, never baked.
+ */
+const REGISTRY_FUNCTION_LAUNCHER = `// Generated by handoff-app (\`build --target registry --package vercel\`). Do not edit.
+// Wraps the Next.js standalone server as a Vercel Build Output API Node function.
+process.env.NODE_ENV = 'production';
+process.chdir(__dirname);
+
+const requiredServerFiles = require('./.next/required-server-files.json');
+const nextConfig = requiredServerFiles.config;
+
+// The standalone runtime reads its resolved config from this env var (mirrors standalone server.js).
+process.env.__NEXT_PRIVATE_STANDALONE_CONFIG = JSON.stringify(nextConfig);
+
+// require('next') first so its module hooks are installed before pulling the internal server lib,
+// matching the require order of the generated standalone server.js.
+require('next');
+const { getRequestHandlers } = require('next/dist/server/lib/start-server');
+
+// Initialize the router-server handler once on cold start and reuse it across warm invocations.
+// This is the same handler the standalone server.js uses; it does NOT bind a port (the port bind
+// lives in startServer, which we never call), so it fits the (req, res) Node function contract.
+let handlersPromise;
+const ready = () =>
+  (handlersPromise =
+    handlersPromise ||
+    getRequestHandlers({
+      dir: __dirname,
+      port: parseInt(process.env.PORT, 10) || 3000,
+      hostname: process.env.HOSTNAME || 'localhost',
+      isDev: false,
+      minimalMode: false,
+    }));
+
+module.exports = async (req, res) => {
+  const { requestHandler } = await ready();
+  return requestHandler(req, res);
+};
+`;
+
+/** Build Output API Node serverless-function config (`.vc-config.json`). */
+interface VercelNodeFunctionConfig {
+  runtime: string;
+  handler: string;
+  launcherType: 'Nodejs';
+}
+
+/**
+ * Options for {@link writeRegistryVercelOutput}. The build module owns the standalone assembly (entry
+ * flattening + static/public/config layout) and passes it in, keeping this seam free of any
+ * standalone-layout knowledge and avoiding a circular import.
+ */
+export interface RegistryVercelOutputOptions {
+  /** Absolute path of the staged Next app (source of `.next/static` + `public`). */
+  appPath: string;
+  /** Absolute path of the Next `standalone` build root (`<appPath>/.next/standalone`). */
+  standaloneRoot: string;
+  /**
+   * Lay the standalone bundle out under the given entry dir (flatten the server entry, copy static
+   * assets, public tree, and runtime config beside it) and return the absolute server-entry path.
+   * Shared with the standalone deliverable so both layouts stay identical.
+   */
+  assembleStandalone: (handoff: Handoff, appPath: string, standaloneRoot: string, entryDir: string) => Promise<string>;
+}
+
+/**
+ * Copy the genuinely-static prerendered pages into the Edge CDN layer (`static/`) so their HTML and
+ * `_next/data` JSON are served directly by the CDN instead of invoking the single registry function.
+ * This is a load/latency optimization, not a correctness requirement: the function (see the launcher)
+ * now resolves on-demand data routes itself, so anything not copied here still resolves via the
+ * catch-all.
+ *
+ * Routes materialized from the mutable docs catch-all also appear in `routes` when package defaults
+ * are prerendered. They are identified by `srcRoute` and deliberately left behind the function so a
+ * published DB record can override the fallback. Other `fallback:'blocking'` dynamic routes are
+ * absent and naturally reach the function. Immutable pages — e.g. the header's `<Link href="/">`
+ * prefetch of `/_next/data/<buildId>/index.json` — are served straight from the CDN.
+ *
+ * No-op when nothing is prerendered (empty `routes`). Paths are emitted base-path-less, matching the
+ * existing `_next/static` copy and the registry route table.
+ */
+const copyPrerenderedStaticPages = async (appPath: string, staticOutDir: string): Promise<void> => {
+  const nextDir = path.resolve(appPath, '.next');
+  const manifestPath = path.join(nextDir, 'prerender-manifest.json');
+  const buildIdPath = path.join(nextDir, 'BUILD_ID');
+  if (!fs.existsSync(manifestPath) || !fs.existsSync(buildIdPath)) {
+    return;
+  }
+
+  const manifest = (await fs.readJson(manifestPath)) as {
+    routes?: Record<string, { dataRoute?: string | null; srcRoute?: string | null }>;
+  };
+  const routes = manifest.routes ?? {};
+  const serverPages = path.join(nextDir, 'server', 'pages');
+
+  let copied = 0;
+  for (const [route, routeConfig] of Object.entries(routes)) {
+    // A static copy would win at the Build Output API filesystem route and permanently hide a
+    // published override (and its on-demand revalidation) from the registry function.
+    if (routeConfig.srcRoute === MUTABLE_REGISTRY_PAGE_SRC_ROUTE) {
+      continue;
+    }
+
+    // `.next/server/pages/<rel>.{html,json}` — `/` maps to `index`, nested routes keep their path.
+    const rel = route === '/' ? 'index' : route.replace(/^\/+/, '');
+    const htmlSrc = path.join(serverPages, `${rel}.html`);
+    const jsonSrc = path.join(serverPages, `${rel}.json`);
+
+    if (fs.existsSync(htmlSrc)) {
+      // trailingSlash:true → serve as `<route>/index.html`; `/` → `static/index.html`.
+      const htmlDestDir = route === '/' ? staticOutDir : path.join(staticOutDir, rel);
+      await fs.ensureDir(htmlDestDir);
+      await fs.copy(htmlSrc, path.join(htmlDestDir, 'index.html'), { overwrite: true });
+    }
+
+    // The data URL (with the build's BUILD_ID baked in) comes from the manifest's `dataRoute`.
+    const dataRoute = routeConfig.dataRoute;
+    if (dataRoute && fs.existsSync(jsonSrc)) {
+      const jsonDest = path.join(staticOutDir, dataRoute.replace(/^\/+/, ''));
+      await fs.ensureDir(path.dirname(jsonDest));
+      await fs.copy(jsonSrc, jsonDest, { overwrite: true });
+      copied += 1;
+    }
+  }
+
+  Logger.info(`Copied ${copied} prerendered static page data file(s) into the Edge CDN layer.`);
+};
+
+/**
+ * Package the dynamic registry app as the Vercel Build Output API directory. Lays the traced
+ * standalone bundle into a single Node function (`functions/index.func/`)
+ * wrapping the Next standalone server, copies the immutable static assets + public tree under
+ * `static/` for the Edge CDN, and writes a route table that serves static files first and routes
+ * everything else (SSR pages, the docs read API, the registry API) to the function.
+ *
+ * Hard constraint: `.vercel/output` lives at the repo root with that exact name (see module header).
+ */
+export const writeRegistryVercelOutput = async (handoff: Handoff, options: RegistryVercelOutputOptions): Promise<void> => {
+  const { appPath, standaloneRoot, assembleStandalone } = options;
+
+  const outputPath = getVercelOutputPath(handoff);
+  await fs.remove(outputPath);
+  await fs.ensureDir(outputPath);
+
+  // The function directory *is* the standalone bundle root: the traced server + node_modules, the
+  // server entry flattened to its root, and `.next/static` + public + runtime config beside it. The
+  // launcher constructs a NextServer from this directory, so it needs the full standalone layout.
+  const functionDir = path.join(outputPath, 'functions', `${REGISTRY_FUNCTION_NAME}.func`);
+  await fs.ensureDir(functionDir);
+  await assembleStandalone(handoff, appPath, standaloneRoot, functionDir);
+
+  // The standalone `server.js` binds a port; replace the entry with the Build Output API Node
+  // launcher (a `(req, res)` request listener) and declare the Node runtime so the pg/Neon drivers
+  // work. `server.js` is left in place (harmless, unused) to keep the bundle a valid standalone too.
+  await fs.writeFile(path.join(functionDir, REGISTRY_FUNCTION_HANDLER), REGISTRY_FUNCTION_LAUNCHER);
+  const functionConfig: VercelNodeFunctionConfig = {
+    runtime: VERCEL_NODE_RUNTIME,
+    handler: REGISTRY_FUNCTION_HANDLER,
+    launcherType: 'Nodejs',
+  };
+  await fs.writeFile(path.join(functionDir, '.vc-config.json'), `${JSON.stringify(functionConfig, null, 2)}\n`);
+
+  // Serve the app's immutable assets straight from the Edge CDN. `_next/static` is content-hashed and
+  // public files sit at the URL root; copying them under `static/` lets the route table satisfy them
+  // via `handle: filesystem` before the catch-all reaches the function.
+  const staticOutDir = path.join(outputPath, 'static');
+  await fs.ensureDir(staticOutDir);
+  const nextStaticSrc = path.resolve(appPath, '.next', 'static');
+  if (fs.existsSync(nextStaticSrc)) {
+    await fs.copy(nextStaticSrc, path.join(staticOutDir, '_next', 'static'), { overwrite: true });
+  }
+  const publicSrc = path.resolve(appPath, 'public');
+  if (fs.existsSync(publicSrc)) {
+    await fs.copy(publicSrc, staticOutDir, { overwrite: true });
+  }
+
+  // Serve genuinely-static prerendered pages (HTML + `_next/data` JSON) from the CDN as an
+  // optimization so they skip the function. Dynamic `fallback:'blocking'` pages are not copied (their
+  // data is live), and the function now resolves their on-demand `_next/data` routes itself.
+  await copyPrerenderedStaticPages(appPath, staticOutDir);
+
+  // Route table: try static files first (`handle: filesystem` serves anything copied into static/),
+  // then route every remaining request — SSR/on-demand pages, their `/_next/data/*` routes,
+  // /api/docs/*, /api/registry/* — to the single function. The `.func` suffix is dropped from the
+  // URL, so `index.func` is reached via `/index`.
+  const config = {
+    version: BUILD_OUTPUT_API_VERSION,
+    routes: [{ handle: 'filesystem' }, { src: '/(.*)', dest: `/${REGISTRY_FUNCTION_NAME}` }],
+  };
+  await fs.writeFile(path.join(outputPath, 'config.json'), `${JSON.stringify(config, null, 2)}\n`);
+
+  Logger.success(
+    `Packaged registry Vercel Build Output API artifact at ${outputPath} ` +
+      `(functions/${REGISTRY_FUNCTION_NAME}.func + static/ + config.json).`
+  );
+};

package/src/app-builder/watchers/utils.ts

@@ -7,6 +7,8 @@ export interface WatcherState {
   runtimeComponentsWatcher: chokidar.FSWatcher | null;
   runtimeConfigurationWatcher: chokidar.FSWatcher | null;
   componentDirectoriesWatcher: chokidar.FSWatcher | null;
+  /** Watches entries.patterns parent directories for newly created pattern subdirectories. */
+  patternDirectoriesWatcher: chokidar.FSWatcher | null;
 }
 
 /**

package/src/app-builder/watchers.ts

@@ -2,6 +2,7 @@ import chokidar from 'chokidar';
 import fs from 'fs-extra';
 import path from 'path';
 import Handoff from '..';
+import { buildPatterns } from '../pipeline/patterns';
 import processComponents, { ComponentSegment } from '../transformers/preview/component/builder';
 import { buildMainCss } from '../transformers/preview/component/css';
 import { buildMainJS } from '../transformers/preview/component/javascript';
@@ -209,6 +210,15 @@ export const watchRuntimeComponents = (
   }
 };
 
+const rebuildPatternComponentPreviews = async (handoff: Handoff, patternId: string) => {
+  const pattern = handoff.runtimeConfig?.entries?.patterns?.[patternId];
+  if (!pattern?.components?.length) return;
+
+  for (const ref of pattern.components) {
+    await processComponents(handoff, ref.id, ComponentSegment.Previews);
+  }
+};
+
 /**
  * Watches the runtime configuration for changes.
  *
@@ -256,6 +266,8 @@ export const watchRuntimeConfiguration = (handoff: Handoff, state: WatcherState)
                 await processComponents(handoff);
               } else if (handle) {
                 await handle.apply(handoff, entryAfter?.entityId);
+              } else if (entryAfter?.kind === 'pattern') {
+                await rebuildPatternComponentPreviews(handoff, entryAfter.entityId);
               } else {
                 const effectiveId = entryAfter?.entityId ?? path.basename(path.dirname(changedFile));
                 await processComponents(handoff, effectiveId);
@@ -273,22 +285,50 @@ export const watchRuntimeConfiguration = (handoff: Handoff, state: WatcherState)
 };
 
 /**
- * Watches the parent component directories from config.entries.components
- * for new components being added. When a new config file (e.g. button.json)
- * appears in a new subdirectory, reloads the runtime config and restarts
- * the component/configuration watchers so the new component is picked up.
+ * Shared factory for watching a parent directory for newly created entity
+ * subdirectories (components or patterns). Handles the common scaffolding so
+ * that callers only describe what differs for their entity kind:
+ *
+ *  - which config-entry paths to watch
+ *  - how to read the current known ids after a reload
+ *  - which WatcherState slot to use
+ *  - a log label for the entity kind
+ *  - the rebuild work to run once the runtime config is fresh
  */
-export const watchComponentDirectories = (handoff: Handoff, state: WatcherState, chokidarConfig: chokidar.WatchOptions) => {
-  if (state.componentDirectoriesWatcher) {
-    state.componentDirectoriesWatcher.close();
+const watchEntityDirectories = (handoff: Handoff, state: WatcherState, chokidarConfig: chokidar.WatchOptions, options: {
+  /** Config paths to watch, e.g. handoff.config.entries?.components */
+  getConfigPaths: (handoff: Handoff) => string[];
+  /** Current known entity ids from runtime config, called again after reload to refresh the set */
+  getKnownIds: (handoff: Handoff) => string[];
+  /** Read the active FSWatcher from state */
+  getWatcher: (state: WatcherState) => chokidar.FSWatcher | null;
+  /** Write the active FSWatcher back into state */
+  setWatcher: (state: WatcherState, watcher: chokidar.FSWatcher) => void;
+  /** Prefix for the scheduleHandler key, e.g. 'newComponent' or 'newPattern' */
+  scheduleKeyPrefix: string;
+  /** Human-readable label used in log messages, e.g. 'component' or 'pattern' */
+  entityLabel: string;
+  /**
+   * Entity-specific rebuild work, called after reload + persistClientConfig +
+   * watcher re-registration. Receives the handoff instance (with fresh runtime
+   * config), the triggering directory name, and actual entity ids discovered
+   * after reload.
+   */
+  onDetected: (handoff: Handoff, context: { dirName: string; addedIds: string[] }) => Promise<void>;
+}) => {
+  const { getConfigPaths, getKnownIds, getWatcher, setWatcher, scheduleKeyPrefix, entityLabel, onDetected } = options;
+
+  const existingWatcher = getWatcher(state);
+  if (existingWatcher) {
+    existingWatcher.close();
   }
 
-  const componentPaths = handoff.config.entries?.components ?? [];
-  if (componentPaths.length === 0) return;
+  const configPaths = getConfigPaths(handoff);
+  if (configPaths.length === 0) return;
 
   const dirsToWatch: string[] = [];
-  for (const componentPath of componentPaths) {
-    const resolved = path.resolve(handoff.workingPath, componentPath);
+  for (const configPath of configPaths) {
+    const resolved = path.resolve(handoff.workingPath, configPath);
     if (fs.existsSync(resolved) && fs.statSync(resolved).isDirectory()) {
       dirsToWatch.push(resolved);
     }
@@ -296,40 +336,124 @@ export const watchComponentDirectories = (handoff: Handoff, state: WatcherState,
 
   if (dirsToWatch.length === 0) return;
 
-  const knownComponents = new Set(Object.keys(handoff.runtimeConfig?.entries?.components ?? {}));
+  // Snapshot known ids at watch startup so we only react to genuinely new
+  // entities, not to file changes inside already-known directories.
+  const knownIds = new Set(getKnownIds(handoff));
 
-  state.componentDirectoriesWatcher = chokidar.watch(dirsToWatch, {
+  const watcher = chokidar.watch(dirsToWatch, {
     ...chokidarConfig,
     depth: 1,
   });
+  setWatcher(state, watcher);
 
-  state.componentDirectoriesWatcher.on('add', async (file) => {
+  watcher.on('add', async (file) => {
     const basename = path.basename(file);
     const dirName = path.basename(path.dirname(file));
 
-    const isConfigFile = basename.endsWith('.json') || basename.endsWith('.js') || basename.endsWith('.cjs');
-    const isNewComponent = isConfigFile && basename.startsWith(dirName) && !knownComponents.has(dirName);
+    // Only react to the primary declaration file for the directory (e.g.
+    // button.json, button.js, or button.handoff.ts inside a button/ subdir).
+    // The basename.startsWith(dirName) guard below ensures .ts here only
+    // ever matches files named after their parent directory, not arbitrary
+    // TypeScript source files.
+    const isConfigFile = basename.endsWith('.json') || basename.endsWith('.js') || basename.endsWith('.cjs') || basename.endsWith('.ts');
+    const isNewEntity = isConfigFile && basename.startsWith(dirName) && !knownIds.has(dirName);
 
-    if (!isNewComponent) return;
+    if (!isNewEntity) return;
 
-    await scheduleHandler(state, `newComponent:${dirName}`, async () => {
+    await scheduleHandler(state, `${scheduleKeyPrefix}:${dirName}`, async () => {
       try {
-        Logger.warn(`New component detected: ${dirName}. Reloading configuration...`);
+        Logger.warn(`New ${entityLabel} detected: ${dirName}. Reloading configuration...`);
+
+        // Snapshot ids before reload so we can tell whether the new entity
+        // was successfully registered afterwards.
+        const idsBefore = new Set(getKnownIds(handoff));
+
         handoff.reload();
-        knownComponents.add(dirName);
 
-        for (const id of Object.keys(handoff.runtimeConfig?.entries?.components ?? {})) {
-          knownComponents.add(id);
+        // Refresh from the post-reload runtime config so any ids that were
+        // discovered alongside the new entity are also marked as known.
+        const idsAfter = getKnownIds(handoff);
+        const addedIds = idsAfter.filter((id) => !idsBefore.has(id));
+        for (const id of idsAfter) {
+          knownIds.add(id);
         }
 
         await persistClientConfig(handoff);
+
+        // Re-register file watchers so the new config file and any runtime
+        // files it introduces are covered going forward. This must happen even
+        // when the file failed to parse so that watchRuntimeConfiguration can
+        // trigger a retry the moment the file is saved with valid content.
         watchRuntimeComponents(handoff, state, getRuntimeComponentsPathsToWatch(handoff));
         watchRuntimeConfiguration(handoff, state);
-        await processComponents(handoff, dirName);
-        await runAllFinalizers(handoff, { patternRebuildComponentIds: [dirName] });
+
+        // If no new ids appeared after reload the file was empty or invalid.
+        // Skip the build — watchRuntimeConfiguration will fire when it is saved.
+        if (addedIds.length === 0) {
+          Logger.warn(`${entityLabel} "${dirName}" config is empty or incomplete — build will run automatically once the file is saved.`);
+          return;
+        }
+
+        await onDetected(handoff, { dirName, addedIds });
       } catch (e) {
-        Logger.error('Error processing new component:', e);
+        Logger.error(`Error processing new ${entityLabel}:`, e);
       }
     });
   });
 };
+
+/**
+ * Watches the parent component directories from config.entries.components for
+ * new components being added. When a new config file appears in a new
+ * subdirectory, reloads the runtime config, restarts the component and
+ * configuration watchers, then builds the new component and any patterns that
+ * reference it.
+ */
+export const watchComponentDirectories = (handoff: Handoff, state: WatcherState, chokidarConfig: chokidar.WatchOptions) => {
+  watchEntityDirectories(handoff, state, chokidarConfig, {
+    getConfigPaths: (h) => h.config.entries?.components ?? [],
+    getKnownIds: (h) => Object.keys(h.runtimeConfig?.entries?.components ?? {}),
+    getWatcher: (s) => s.componentDirectoriesWatcher,
+    setWatcher: (s, w) => { s.componentDirectoriesWatcher = w; },
+    scheduleKeyPrefix: 'newComponent',
+    entityLabel: 'component',
+    onDetected: async (handoff, { addedIds }) => {
+      for (const componentId of addedIds) {
+        await processComponents(handoff, componentId);
+        await runAllFinalizers(handoff, { patternRebuildComponentIds: [componentId] });
+      }
+    },
+  });
+};
+
+/**
+ * Watches the parent pattern directories from config.entries.patterns for new
+ * patterns being added. The rebuild sequence intentionally differs from
+ * watchComponentDirectories because the dependency arrow is reversed: a new
+ * pattern references existing components, so we rebuild only the preview
+ * segment of those components (to produce the __pattern_* HTML files that
+ * injectPatternPreviews registered) before composing the pattern itself.
+ */
+export const watchPatternDirectories = (handoff: Handoff, state: WatcherState, chokidarConfig: chokidar.WatchOptions) => {
+  watchEntityDirectories(handoff, state, chokidarConfig, {
+    getConfigPaths: (h) => h.config.entries?.patterns ?? [],
+    getKnownIds: (h) => Object.keys(h.runtimeConfig?.entries?.patterns ?? {}),
+    getWatcher: (s) => s.patternDirectoriesWatcher,
+    setWatcher: (s, w) => { s.patternDirectoriesWatcher = w; },
+    scheduleKeyPrefix: 'newPattern',
+    entityLabel: 'pattern',
+    onDetected: async (handoff, { addedIds }) => {
+      // Rebuild only the previews segment for each component the new pattern
+      // references. Their JS/CSS/structure are unchanged — only the new
+      // synthetic preview HTML files need to be generated so that buildPatterns
+      // can assemble the pattern from them.
+      for (const patternId of addedIds) {
+        await rebuildPatternComponentPreviews(handoff, patternId);
+      }
+
+      // Build only the new pattern directly rather than going through
+      // runAllFinalizers, which would rebuild all patterns unnecessarily.
+      await buildPatterns(handoff, { onlyPatternIds: new Set(addedIds) });
+    },
+  });
+};

package/src/app-builder/websocket.ts

@@ -1,4 +1,4 @@
-import { WebSocket } from 'ws';
+import { WebSocket, WebSocketServer } from 'ws';
 import { Logger } from '../utils/logger';
 
 export interface HandoffWebSocket extends WebSocket {
@@ -15,7 +15,7 @@ export interface HandoffWebSocket extends WebSocket {
 export const createWebSocketServer = async (port: number = 3001) => {
   Logger.info(`Starting WebSocket server for live reload on port ${port}…`);
 
-  const wss = new WebSocket.Server({ port });
+  const wss = new WebSocketServer({ port });
 
   wss.on('listening', () => {
     Logger.info(`WebSocket server listening on ws://localhost:${port} (live reload)`);

package/src/artifacts/README.md

@@ -0,0 +1,14 @@
+# Artifacts Module
+
+Shared v2 artifact contract: the structured artifact/build-metadata model the workspace and
+registry tracks both produce and consume, plus the one canonical artifact URL builder used by
+all generated HTML and docs read data. Pure types and utilities — no artifact is read or written
+here; consumers (store, docs read API, build, publish/ingest) come in later issues.
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `types.ts` | `ArtifactDescriptor`, `ArtifactReference`, `ArtifactBuildMetadata`, `ArtifactSizeDiagnostics`, artifact kind/owner/status unions, and shared-artifact/manifest path + format-version constants |
+| `url.ts` | `buildArtifactUrl()`, `normalizeBasePath()`, `ARTIFACTS_ROUTE_SEGMENT` — centralized `{basePath}/api/docs/artifacts/{path}` URL builder (segment-encoded, basePath-preserved, never query strings) |
+| `index.ts` | Barrel re-exports |

package/src/artifacts/index.ts

@@ -0,0 +1,17 @@
+export {
+  ARTIFACT_METADATA_PATH,
+  REACT_PREVIEW_FORMAT_VERSION,
+  SHARED_MAIN_CSS_ARTIFACT_PATH,
+  SHARED_MAIN_JS_ARTIFACT_PATH,
+  SHARED_STYLES_CSS_ARTIFACT_PATH,
+  type ArtifactBuildMetadata,
+  type ArtifactBuildStatus,
+  type ArtifactDescriptor,
+  type ArtifactKind,
+  type ArtifactOwnerKind,
+  type ArtifactReference,
+  type ArtifactReferenceKind,
+  type ArtifactSizeDiagnostics,
+} from './types';
+
+export { ARTIFACTS_ROUTE_SEGMENT, buildArtifactUrl, normalizeBasePath } from './url';