handoff-app 1.2.2-7 → 2.0.0-1

package/dist/app-builder/vercel-output.js

@@ -0,0 +1,259 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.writeRegistryVercelOutput = exports.writeStaticVercelOutput = exports.getVercelOutputPath = void 0;
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const path_1 = __importDefault(require("path"));
+const logger_1 = require("../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. */
+const getVercelOutputPath = (handoff) => path_1.default.resolve(handoff.workingPath, '.vercel', 'output');
+exports.getVercelOutputPath = getVercelOutputPath;
+/**
+ * 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) => {
+    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>`).
+ */
+const writeStaticVercelOutput = (handoff, exportDir) => __awaiter(void 0, void 0, void 0, function* () {
+    var _a, _b;
+    const outputPath = (0, exports.getVercelOutputPath)(handoff);
+    yield fs_extra_1.default.remove(outputPath);
+    yield fs_extra_1.default.ensureDir(outputPath);
+    // Lay the export under static/ — pure CDN files, served directly by Vercel.
+    const staticDir = path_1.default.join(outputPath, 'static');
+    yield fs_extra_1.default.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((_b = (_a = handoff.config) === null || _a === void 0 ? void 0 : _a.app) === null || _b === void 0 ? void 0 : _b.base_path);
+    const config = {
+        version: BUILD_OUTPUT_API_VERSION,
+        trailingSlash: true,
+    };
+    if (basePath) {
+        config.basePath = basePath;
+    }
+    yield fs_extra_1.default.writeFile(path_1.default.join(outputPath, 'config.json'), `${JSON.stringify(config, null, 2)}\n`);
+    logger_1.Logger.success(`Packaged static Vercel Build Output API artifact at ${outputPath} (static/ + config.json).`);
+});
+exports.writeStaticVercelOutput = writeStaticVercelOutput;
+/**
+ * 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);
+};
+`;
+/**
+ * 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 = (appPath, staticOutDir) => __awaiter(void 0, void 0, void 0, function* () {
+    var _a;
+    const nextDir = path_1.default.resolve(appPath, '.next');
+    const manifestPath = path_1.default.join(nextDir, 'prerender-manifest.json');
+    const buildIdPath = path_1.default.join(nextDir, 'BUILD_ID');
+    if (!fs_extra_1.default.existsSync(manifestPath) || !fs_extra_1.default.existsSync(buildIdPath)) {
+        return;
+    }
+    const manifest = (yield fs_extra_1.default.readJson(manifestPath));
+    const routes = (_a = manifest.routes) !== null && _a !== void 0 ? _a : {};
+    const serverPages = path_1.default.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_1.default.join(serverPages, `${rel}.html`);
+        const jsonSrc = path_1.default.join(serverPages, `${rel}.json`);
+        if (fs_extra_1.default.existsSync(htmlSrc)) {
+            // trailingSlash:true → serve as `<route>/index.html`; `/` → `static/index.html`.
+            const htmlDestDir = route === '/' ? staticOutDir : path_1.default.join(staticOutDir, rel);
+            yield fs_extra_1.default.ensureDir(htmlDestDir);
+            yield fs_extra_1.default.copy(htmlSrc, path_1.default.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_extra_1.default.existsSync(jsonSrc)) {
+            const jsonDest = path_1.default.join(staticOutDir, dataRoute.replace(/^\/+/, ''));
+            yield fs_extra_1.default.ensureDir(path_1.default.dirname(jsonDest));
+            yield fs_extra_1.default.copy(jsonSrc, jsonDest, { overwrite: true });
+            copied += 1;
+        }
+    }
+    logger_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).
+ */
+const writeRegistryVercelOutput = (handoff, options) => __awaiter(void 0, void 0, void 0, function* () {
+    const { appPath, standaloneRoot, assembleStandalone } = options;
+    const outputPath = (0, exports.getVercelOutputPath)(handoff);
+    yield fs_extra_1.default.remove(outputPath);
+    yield fs_extra_1.default.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_1.default.join(outputPath, 'functions', `${REGISTRY_FUNCTION_NAME}.func`);
+    yield fs_extra_1.default.ensureDir(functionDir);
+    yield 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.
+    yield fs_extra_1.default.writeFile(path_1.default.join(functionDir, REGISTRY_FUNCTION_HANDLER), REGISTRY_FUNCTION_LAUNCHER);
+    const functionConfig = {
+        runtime: VERCEL_NODE_RUNTIME,
+        handler: REGISTRY_FUNCTION_HANDLER,
+        launcherType: 'Nodejs',
+    };
+    yield fs_extra_1.default.writeFile(path_1.default.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_1.default.join(outputPath, 'static');
+    yield fs_extra_1.default.ensureDir(staticOutDir);
+    const nextStaticSrc = path_1.default.resolve(appPath, '.next', 'static');
+    if (fs_extra_1.default.existsSync(nextStaticSrc)) {
+        yield fs_extra_1.default.copy(nextStaticSrc, path_1.default.join(staticOutDir, '_next', 'static'), { overwrite: true });
+    }
+    const publicSrc = path_1.default.resolve(appPath, 'public');
+    if (fs_extra_1.default.existsSync(publicSrc)) {
+        yield fs_extra_1.default.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.
+    yield 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}` }],
+    };
+    yield fs_extra_1.default.writeFile(path_1.default.join(outputPath, 'config.json'), `${JSON.stringify(config, null, 2)}\n`);
+    logger_1.Logger.success(`Packaged registry Vercel Build Output API artifact at ${outputPath} ` +
+        `(functions/${REGISTRY_FUNCTION_NAME}.func + static/ + config.json).`);
+});
+exports.writeRegistryVercelOutput = writeRegistryVercelOutput;

package/dist/app-builder/watchers/utils.d.ts

@@ -5,6 +5,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;
 }
 /**
  * Schedules a handler for execution with mutual exclusion and per-source

package/dist/app-builder/watchers.d.ts

@@ -36,9 +36,19 @@ export declare const watchRuntimeComponents: (handoff: Handoff, state: WatcherSt
  */
 export declare const watchRuntimeConfiguration: (handoff: Handoff, state: WatcherState) => void;
 /**
- * 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.
+ * 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 declare const watchComponentDirectories: (handoff: Handoff, state: WatcherState, chokidarConfig: chokidar.WatchOptions) => void;
+/**
+ * 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 declare const watchPatternDirectories: (handoff: Handoff, state: WatcherState, chokidarConfig: chokidar.WatchOptions) => void;

package/dist/app-builder/watchers.js

@@ -35,10 +35,11 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.watchComponentDirectories = exports.watchRuntimeConfiguration = exports.watchRuntimeComponents = exports.watchGlobalEntries = exports.watchPages = exports.watchAppSource = exports.watchPublicDirectory = exports.mapEntryTypeToSegment = exports.getRuntimeComponentsPathsToWatch = void 0;
+exports.watchPatternDirectories = exports.watchComponentDirectories = exports.watchRuntimeConfiguration = exports.watchRuntimeComponents = exports.watchGlobalEntries = exports.watchPages = exports.watchAppSource = exports.watchPublicDirectory = exports.mapEntryTypeToSegment = exports.getRuntimeComponentsPathsToWatch = void 0;
 const chokidar_1 = __importDefault(require("chokidar"));
 const fs_extra_1 = __importDefault(require("fs-extra"));
 const path_1 = __importDefault(require("path"));
+const patterns_1 = require("../pipeline/patterns");
 const builder_1 = __importStar(require("../transformers/preview/component/builder"));
 const css_1 = require("../transformers/preview/component/css");
 const javascript_1 = require("../transformers/preview/component/javascript");
@@ -226,6 +227,15 @@ const watchRuntimeComponents = (handoff, state, runtimeComponentPathsToWatch) =>
     }
 };
 exports.watchRuntimeComponents = watchRuntimeComponents;
+const rebuildPatternComponentPreviews = (handoff, patternId) => __awaiter(void 0, void 0, void 0, function* () {
+    var _a, _b, _c, _d;
+    const pattern = (_c = (_b = (_a = handoff.runtimeConfig) === null || _a === void 0 ? void 0 : _a.entries) === null || _b === void 0 ? void 0 : _b.patterns) === null || _c === void 0 ? void 0 : _c[patternId];
+    if (!((_d = pattern === null || pattern === void 0 ? void 0 : pattern.components) === null || _d === void 0 ? void 0 : _d.length))
+        return;
+    for (const ref of pattern.components) {
+        yield (0, builder_1.default)(handoff, ref.id, builder_1.ComponentSegment.Previews);
+    }
+});
 /**
  * Watches the runtime configuration for changes.
  *
@@ -269,6 +279,9 @@ const watchRuntimeConfiguration = (handoff, state) => {
                             else if (handle) {
                                 yield handle.apply(handoff, entryAfter === null || entryAfter === void 0 ? void 0 : entryAfter.entityId);
                             }
+                            else if ((entryAfter === null || entryAfter === void 0 ? void 0 : entryAfter.kind) === 'pattern') {
+                                yield rebuildPatternComponentPreviews(handoff, entryAfter.entityId);
+                            }
                             else {
                                 const effectiveId = (_a = entryAfter === null || entryAfter === void 0 ? void 0 : entryAfter.entityId) !== null && _a !== void 0 ? _a : path_1.default.basename(path_1.default.dirname(changedFile));
                                 yield (0, builder_1.default)(handoff, effectiveId);
@@ -286,56 +299,138 @@ const watchRuntimeConfiguration = (handoff, state) => {
 };
 exports.watchRuntimeConfiguration = watchRuntimeConfiguration;
 /**
- * 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
  */
-const watchComponentDirectories = (handoff, state, chokidarConfig) => {
-    var _a, _b, _c, _d, _e;
-    if (state.componentDirectoriesWatcher) {
-        state.componentDirectoriesWatcher.close();
+const watchEntityDirectories = (handoff, state, chokidarConfig, options) => {
+    const { getConfigPaths, getKnownIds, getWatcher, setWatcher, scheduleKeyPrefix, entityLabel, onDetected } = options;
+    const existingWatcher = getWatcher(state);
+    if (existingWatcher) {
+        existingWatcher.close();
     }
-    const componentPaths = (_b = (_a = handoff.config.entries) === null || _a === void 0 ? void 0 : _a.components) !== null && _b !== void 0 ? _b : [];
-    if (componentPaths.length === 0)
+    const configPaths = getConfigPaths(handoff);
+    if (configPaths.length === 0)
         return;
     const dirsToWatch = [];
-    for (const componentPath of componentPaths) {
-        const resolved = path_1.default.resolve(handoff.workingPath, componentPath);
+    for (const configPath of configPaths) {
+        const resolved = path_1.default.resolve(handoff.workingPath, configPath);
         if (fs_extra_1.default.existsSync(resolved) && fs_extra_1.default.statSync(resolved).isDirectory()) {
             dirsToWatch.push(resolved);
         }
     }
     if (dirsToWatch.length === 0)
         return;
-    const knownComponents = new Set(Object.keys((_e = (_d = (_c = handoff.runtimeConfig) === null || _c === void 0 ? void 0 : _c.entries) === null || _d === void 0 ? void 0 : _d.components) !== null && _e !== void 0 ? _e : {}));
-    state.componentDirectoriesWatcher = chokidar_1.default.watch(dirsToWatch, Object.assign(Object.assign({}, chokidarConfig), { depth: 1 }));
-    state.componentDirectoriesWatcher.on('add', (file) => __awaiter(void 0, void 0, void 0, function* () {
+    // 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));
+    const watcher = chokidar_1.default.watch(dirsToWatch, Object.assign(Object.assign({}, chokidarConfig), { depth: 1 }));
+    setWatcher(state, watcher);
+    watcher.on('add', (file) => __awaiter(void 0, void 0, void 0, function* () {
         const basename = path_1.default.basename(file);
         const dirName = path_1.default.basename(path_1.default.dirname(file));
-        const isConfigFile = basename.endsWith('.json') || basename.endsWith('.js') || basename.endsWith('.cjs');
-        const isNewComponent = isConfigFile && basename.startsWith(dirName) && !knownComponents.has(dirName);
-        if (!isNewComponent)
+        // 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 (!isNewEntity)
             return;
-        yield (0, utils_1.scheduleHandler)(state, `newComponent:${dirName}`, () => __awaiter(void 0, void 0, void 0, function* () {
-            var _a, _b, _c;
+        yield (0, utils_1.scheduleHandler)(state, `${scheduleKeyPrefix}:${dirName}`, () => __awaiter(void 0, void 0, void 0, function* () {
             try {
-                logger_1.Logger.warn(`New component detected: ${dirName}. Reloading configuration...`);
+                logger_1.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((_c = (_b = (_a = handoff.runtimeConfig) === null || _a === void 0 ? void 0 : _a.entries) === null || _b === void 0 ? void 0 : _b.components) !== null && _c !== void 0 ? _c : {})) {
-                    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);
                 }
                 yield (0, client_config_1.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.
                 (0, exports.watchRuntimeComponents)(handoff, state, (0, component_1.getRuntimeComponentsPathsToWatch)(handoff));
                 (0, exports.watchRuntimeConfiguration)(handoff, state);
-                yield (0, builder_1.default)(handoff, dirName);
-                yield (0, config_diff_1.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_1.Logger.warn(`${entityLabel} "${dirName}" config is empty or incomplete — build will run automatically once the file is saved.`);
+                    return;
+                }
+                yield onDetected(handoff, { dirName, addedIds });
             }
             catch (e) {
-                logger_1.Logger.error('Error processing new component:', e);
+                logger_1.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.
+ */
+const watchComponentDirectories = (handoff, state, chokidarConfig) => {
+    watchEntityDirectories(handoff, state, chokidarConfig, {
+        getConfigPaths: (h) => { var _a, _b; return (_b = (_a = h.config.entries) === null || _a === void 0 ? void 0 : _a.components) !== null && _b !== void 0 ? _b : []; },
+        getKnownIds: (h) => { var _a, _b, _c; return Object.keys((_c = (_b = (_a = h.runtimeConfig) === null || _a === void 0 ? void 0 : _a.entries) === null || _b === void 0 ? void 0 : _b.components) !== null && _c !== void 0 ? _c : {}); },
+        getWatcher: (s) => s.componentDirectoriesWatcher,
+        setWatcher: (s, w) => { s.componentDirectoriesWatcher = w; },
+        scheduleKeyPrefix: 'newComponent',
+        entityLabel: 'component',
+        onDetected: (handoff_1, _a) => __awaiter(void 0, [handoff_1, _a], void 0, function* (handoff, { addedIds }) {
+            for (const componentId of addedIds) {
+                yield (0, builder_1.default)(handoff, componentId);
+                yield (0, config_diff_1.runAllFinalizers)(handoff, { patternRebuildComponentIds: [componentId] });
+            }
+        }),
+    });
+};
 exports.watchComponentDirectories = watchComponentDirectories;
+/**
+ * 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.
+ */
+const watchPatternDirectories = (handoff, state, chokidarConfig) => {
+    watchEntityDirectories(handoff, state, chokidarConfig, {
+        getConfigPaths: (h) => { var _a, _b; return (_b = (_a = h.config.entries) === null || _a === void 0 ? void 0 : _a.patterns) !== null && _b !== void 0 ? _b : []; },
+        getKnownIds: (h) => { var _a, _b, _c; return Object.keys((_c = (_b = (_a = h.runtimeConfig) === null || _a === void 0 ? void 0 : _a.entries) === null || _b === void 0 ? void 0 : _b.patterns) !== null && _c !== void 0 ? _c : {}); },
+        getWatcher: (s) => s.patternDirectoriesWatcher,
+        setWatcher: (s, w) => { s.patternDirectoriesWatcher = w; },
+        scheduleKeyPrefix: 'newPattern',
+        entityLabel: 'pattern',
+        onDetected: (handoff_1, _a) => __awaiter(void 0, [handoff_1, _a], void 0, function* (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) {
+                yield rebuildPatternComponentPreviews(handoff, patternId);
+            }
+            // Build only the new pattern directly rather than going through
+            // runAllFinalizers, which would rebuild all patterns unnecessarily.
+            yield (0, patterns_1.buildPatterns)(handoff, { onlyPatternIds: new Set(addedIds) });
+        }),
+    });
+};
+exports.watchPatternDirectories = watchPatternDirectories;

package/dist/app-builder/websocket.js

@@ -21,7 +21,7 @@ const logger_1 = require("../utils/logger");
  */
 const createWebSocketServer = (...args_1) => __awaiter(void 0, [...args_1], void 0, function* (port = 3001) {
     logger_1.Logger.info(`Starting WebSocket server for live reload on port ${port}…`);
-    const wss = new ws_1.WebSocket.Server({ port });
+    const wss = new ws_1.WebSocketServer({ port });
     wss.on('listening', () => {
         logger_1.Logger.info(`WebSocket server listening on ws://localhost:${port} (live reload)`);
     });

package/dist/artifacts/index.d.ts

@@ -0,0 +1,2 @@
+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, ASSETS_ROUTE_SEGMENT, buildArtifactUrl, buildAssetDownloadUrl, buildAssetUrl, normalizeBasePath, } from './url';

package/dist/artifacts/index.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeBasePath = exports.buildAssetUrl = exports.buildAssetDownloadUrl = exports.buildArtifactUrl = exports.ASSETS_ROUTE_SEGMENT = exports.ARTIFACTS_ROUTE_SEGMENT = exports.SHARED_STYLES_CSS_ARTIFACT_PATH = exports.SHARED_MAIN_JS_ARTIFACT_PATH = exports.SHARED_MAIN_CSS_ARTIFACT_PATH = exports.REACT_PREVIEW_FORMAT_VERSION = exports.ARTIFACT_METADATA_PATH = void 0;
+var types_1 = require("./types");
+Object.defineProperty(exports, "ARTIFACT_METADATA_PATH", { enumerable: true, get: function () { return types_1.ARTIFACT_METADATA_PATH; } });
+Object.defineProperty(exports, "REACT_PREVIEW_FORMAT_VERSION", { enumerable: true, get: function () { return types_1.REACT_PREVIEW_FORMAT_VERSION; } });
+Object.defineProperty(exports, "SHARED_MAIN_CSS_ARTIFACT_PATH", { enumerable: true, get: function () { return types_1.SHARED_MAIN_CSS_ARTIFACT_PATH; } });
+Object.defineProperty(exports, "SHARED_MAIN_JS_ARTIFACT_PATH", { enumerable: true, get: function () { return types_1.SHARED_MAIN_JS_ARTIFACT_PATH; } });
+Object.defineProperty(exports, "SHARED_STYLES_CSS_ARTIFACT_PATH", { enumerable: true, get: function () { return types_1.SHARED_STYLES_CSS_ARTIFACT_PATH; } });
+var url_1 = require("./url");
+Object.defineProperty(exports, "ARTIFACTS_ROUTE_SEGMENT", { enumerable: true, get: function () { return url_1.ARTIFACTS_ROUTE_SEGMENT; } });
+Object.defineProperty(exports, "ASSETS_ROUTE_SEGMENT", { enumerable: true, get: function () { return url_1.ASSETS_ROUTE_SEGMENT; } });
+Object.defineProperty(exports, "buildArtifactUrl", { enumerable: true, get: function () { return url_1.buildArtifactUrl; } });
+Object.defineProperty(exports, "buildAssetDownloadUrl", { enumerable: true, get: function () { return url_1.buildAssetDownloadUrl; } });
+Object.defineProperty(exports, "buildAssetUrl", { enumerable: true, get: function () { return url_1.buildAssetUrl; } });
+Object.defineProperty(exports, "normalizeBasePath", { enumerable: true, get: function () { return url_1.normalizeBasePath; } });