handoff-app 1.2.2-6 → 1.2.2

package/.claude/settings.local.json

@@ -0,0 +1,75 @@
+{
+  "permissions": {
+    "allow": [
+      "Read(//Users/domagojgojak/.claude/skills/to-prd/**)",
+      "Read(//Users/domagojgojak/.claude/skills/**)",
+      "Bash(python3 -c \"import json,sys; d=json.load\\(sys.stdin\\); print\\('name:',d.get\\('name'\\)\\); print\\('version:',d.get\\('version'\\)\\); print\\('bin:',json.dumps\\(d.get\\('bin'\\),indent=2\\)\\); print\\('main:',d.get\\('main'\\)\\); print\\('scripts:',json.dumps\\(d.get\\('scripts'\\),indent=2\\)\\)\")",
+      "Bash(python3 -c \"import json,sys;d=json.load\\(sys.stdin\\);dd={**d.get\\('dependencies',{}\\),**d.get\\('devDependencies',{}\\)};print\\([k for k in dd if any\\(t in k for t in ['jest','vitest','playwright','mocha','supertest','@testing']\\)] or 'none'\\)\")",
+      "Bash(python3 -c \"import json,sys;d=json.load\\(sys.stdin\\);print\\(d.get\\('files','\\(no files field\\)'\\)\\)\")",
+      "Bash(npx tsc *)",
+      "Bash(npx next *)",
+      "Bash(node *)",
+      "Read(//Users/domagojgojak/source/repos/convertiv/handoff-demo/**)",
+      "Bash(npm run *)",
+      "Bash(git -C /Users/domagojgojak/source/repos/convertiv/handoff-app status --short)",
+      "Bash(git -C /Users/domagojgojak/source/repos/convertiv/handoff-app diff --stat)",
+      "Bash(curl -s -o /dev/null -w 'HTTP %{http_code} CT %{content_type}\\\\n' http://localhost:3987/api/docs/artifacts/component/badge.css)",
+      "Bash(curl -s -o /dev/null -w 'HTTP %{http_code} CT %{content_type}\\\\n' http://localhost:3987/api/docs/artifacts/component/badge-primary.html)",
+      "Bash(curl -s -o /dev/null -w 'HTTP %{http_code} CT %{content_type}\\\\n' http://localhost:3987/api/docs/artifacts/component/badge.json)",
+      "Bash(curl -s -o /dev/null -w 'HTTP %{http_code} CT %{content_type}\\\\n' http://localhost:3987/api/docs/artifacts/component/main.js)",
+      "Bash(curl -s -o /dev/null -w 'HTTP %{http_code} CT %{content_type}\\\\n' http://localhost:3987/api/docs/artifacts/pattern/demo.html)",
+      "Bash(curl -s -o /dev/null -w 'HTTP %{http_code} CT %{content_type}\\\\n' http://localhost:3987/api/docs/artifacts/component/assets/script-l0sNRNKZ.js)",
+      "Bash(curl -s -w ' <-HTTP %{http_code}\\\\n' http://localhost:3987/api/docs/artifacts/component/../components.json)",
+      "Bash(curl -s -w ' <-HTTP %{http_code}\\\\n' http://localhost:3987/api/docs/artifacts/component/%2E%2E/secret)",
+      "Bash(curl -s -w ' <-HTTP %{http_code}\\\\n' http://localhost:3987/api/docs/artifacts/component/nope.css)",
+      "Bash(curl -s -o /dev/null -w 'HTTP %{http_code} CT %{content_type}\\\\n' http://localhost:3987/api/docs/artifacts/component/probe.txt)",
+      "Bash(curl -s --path-as-is -o /dev/null -w '%{http_code}\\\\n' http://localhost:3987/api/docs/artifacts/%2E%2E/%2E%2E/secret)",
+      "Bash(curl -s --path-as-is -o /dev/null -w '%{http_code}\\\\n' http://localhost:3987/api/docs/artifacts/component/%2E%2E)",
+      "Bash(curl -s --path-as-is -o /dev/null -w '%{http_code}\\\\n' http://localhost:3987/api/docs/artifacts/component%2F..%2Fcomponents.json)",
+      "Bash(curl -s --path-as-is http://localhost:3987/api/docs/artifacts/component/nope.css)",
+      "Bash(curl -s --path-as-is -o /dev/null -w '%{http_code}\\\\n' http://localhost:3987/api/docs/artifacts/component/../../components.json)",
+      "Bash(curl -s -o /dev/null -w '%{http_code} %{content_type}\\\\n' http://localhost:3987/api/docs/components/badge/previews/primary)",
+      "Bash(curl -s -o /dev/null -w '%{http_code} %{content_type}\\\\n' http://localhost:3987/api/docs/components/badge/inspect/primary)",
+      "Bash(curl -s -o /dev/null -w '%{http_code} %{content_type}\\\\n' http://localhost:3987/api/docs/components/badge/assets/style)",
+      "Bash(curl -s -w ' %{http_code}\\\\n' http://localhost:3987/api/docs/components/badge/assets/client)",
+      "Bash(curl -s -w ' %{http_code}\\\\n' http://localhost:3987/api/docs/components/badge/assets/bogus)",
+      "Bash(curl -sL -o /dev/null -w '%{http_code} %{content_type}\\\\n' http://localhost:3987/api/docs/components/badge/previews/primary/)",
+      "Bash(curl -sL -o /dev/null -w '%{http_code} %{content_type}\\\\n' http://localhost:3987/api/docs/components/badge/inspect/primary/)",
+      "Bash(curl -sL -o /dev/null -w '%{http_code} %{content_type}\\\\n' http://localhost:3987/api/docs/components/badge/assets/style/)",
+      "Bash(curl -sL -w ' %{http_code}\\\\n' http://localhost:3987/api/docs/components/badge/assets/client/)",
+      "Bash(curl -sL -w ' %{http_code}\\\\n' http://localhost:3987/api/docs/components/badge/assets/bogus/)",
+      "Bash(curl -s http://localhost:3987/api/docs/components.json)",
+      "Bash(grep -v \"deprecated\\\\|create-next-app\\\\|migrate\\\\|codemod\\\\|^$\\\\|Disabling\\\\|disable some\\\\|Learn more\\\\|ESLint CLI\")",
+      "Bash(grep -rn \"['\\\\\"\\\\`].*api/\\\\\\(component\\\\|pattern\\\\|components\\\\|patterns\\\\\\)\" src/app src/templates)",
+      "Bash(echo \"EXIT:$?\")",
+      "Bash(git log *)",
+      "Bash(echo \"EXIT: $?\")",
+      "WebSearch",
+      "Bash(python3 -m json.tool)",
+      "Bash(find . -maxdepth 3 -name 'next-server.js')",
+      "Bash(find . -maxdepth 2 -name 'node_modules' -type d)",
+      "Bash(python3 -c \"import json,sys; d=json.load\\(sys.stdin\\); print\\('basePath:',d.get\\('basePath'\\)\\); print\\('dynamicRoutes:',[r['page'] for r in d.get\\('dynamicRoutes',[]\\)]\\); print\\('staticRoutes:',[r['page'] for r in d.get\\('staticRoutes',[]\\)][:20]\\)\")",
+      "WebFetch(domain:raw.githubusercontent.com)",
+      "Bash(python3 -c \"import json,sys; d=json.load\\(sys.stdin\\); print\\('runtime:', json.dumps\\(d.get\\('runtime'\\)\\)\\)\")",
+      "Bash(python3 -c \"import sys,json; d=json.load\\(sys.stdin\\); print\\('appDir/relativeAppDir:', d.get\\('relativeAppDir'\\)\\); print\\('config.distDir:', d['config'].get\\('distDir'\\)\\); print\\('outputFileTracingRoot:', d['config'].get\\('outputFileTracingRoot'\\)\\)\")",
+      "Bash(HOME=/tmp node -e \"try { require\\('./index.js'\\); console.log\\('LOADED OK'\\); } catch\\(e\\){ console.log\\('COLD-START CRASH:', e.code||'', e.message.split\\('\\\\n'\\)[0]\\); }\")",
+      "Bash(cp tsconfig.json /tmp/_tsconfig.bak)",
+      "Bash(python3 -c ' *)",
+      "Bash(npm pack *)",
+      "Bash(python3 -c \"import json; print\\(json.dumps\\(json.load\\(open\\('package.json'\\)\\).get\\('scripts',{}\\),indent=2\\)\\)\")",
+      "Bash(python3 -)",
+      "Bash(curl -s -o /dev/null -w \"%{http_code}\" http://localhost:3000/)",
+      "Bash(pkill -f \"handoff-app dev\")",
+      "Bash(pkill -f \"next dev\")",
+      "Bash(rm -f /tmp/demo_*.html /tmp/handoff-demo-dev.log)",
+      "Bash(grep -vE \"postman|package-lock|package.json$\")",
+      "Bash(mv ./handoff-app-2.0.0.tgz ../handoff-demo/packages/)",
+      "Bash(rm -rf node_modules/handoff-app node_modules/.cache)",
+      "Bash(npm install *)",
+      "Bash(echo \"exit: $?\")",
+      "Bash(echo \"---exit $?---\")",
+      "Bash(git config *)",
+      "Bash(echo \"---exit: $?\")"
+    ]
+  }
+}

package/Changelog.md

@@ -6,19 +6,42 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to
 [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## \[1.2.2] - 2026-04-09
+## \[1.2.2] - TBD
 
-This patch release clears ESLint failures in the Next.js app pages and aligns
-several code paths with the compiler target so production builds succeed without
-enabling `--downlevelIteration`.
+This patch release improves watch-mode reliability for patterns, broadens slot
+default typing, clears downstream lint/build compatibility issues, and fixes a
+few release-branch UI and dependency issues.
 
-### Change
+### Added
 
-* Altered the avaliable types to the SlotMetadata so the default can handle
-  a wide variaty of types - `default?: string | number | boolean | object | any[] | null;`
+* Added `watchPatternDirectories` so newly created pattern subdirectories are
+  detected during `start` without restarting the dev server.
+* Added a shared `NotFound` component and reused it for stale pattern URLs and
+  missing markdown pages.
 
-### Lint and code quality
+### Changed
 
+* Broadened `SlotMetadata.default` so slot defaults can be strings, numbers,
+  booleans, objects, arrays, or `null`.
+* Refactored component and pattern directory watching through a shared
+  `watchEntityDirectories` helper.
+* Downgraded incomplete or mid-edit pattern declarations from hard parse errors
+  to warnings, allowing watch mode to retry automatically after the file is
+  saved with valid content.
+* Removed unneeded theme declarations.
+
+### Fixed
+
+* Fixed watch-mode rebuilds for newly added patterns by rebuilding referenced
+  component previews before composing the new pattern.
+* Fixed pattern watcher edge cases where declaration IDs differ from directory
+  names, and where an initially incomplete pattern config later becomes valid.
+* Fixed `.handoff.ts` declaration files not being detected by the new-entity
+  config-file gate.
+* Extended component build-cache inputs to include pattern config files that
+  reference the component, preventing stale preview output after pattern changes.
+* Fixed select/list handling when a component group or category value is empty.
+* Fixed CSS typing issues and app build issues found during the release branch.
 * Resolved `no-else-return`, `no-unused-vars`, `camelcase`, `prefer-const`,
   `eqeqeq`, `no-nested-ternary`, `no-lonely-if`, and `no-use-before-define`
   across static pages (catch-all docs, assets, foundations, home, system, and
@@ -26,17 +49,16 @@ enabling `--downlevelIteration`.
 * Removed or refactored unused `getStaticProps` context parameters, props, and
   locals; normalized naming (e.g. font machine keys); simplified icon detail
   routing query handling.
-* Reordered helper components (token color/effect/typography tables, component
-  token previews) ahead of page components where required for declaration order.
+* Reordered helper components ahead of page components where required for
+  declaration order.
 * Converted `getComponentPreviews` to a hoisted `function` declaration and
   refactored the component token table for clearer control flow.
+* Avoided iterating `Map`, `Set`, `Iterable`, and `matchAll` results directly in
+  `for...of` where the compile target requires `--downlevelIteration`.
 
-### Build / TypeScript compatibility
+### Security
 
-* Avoid iterating `Map` / `Set` / `Iterable` / `matchAll` results directly in
-  `for...of` where the compile target requires it: use `Array.from(...)` or
-  equivalent helpers in the config-diff registry, snapshot diff, CSF import
-  parsing, and component artifact sync.
+* Updated Vite to address a security issue.
 
 ## \[1.2.1] - 2026-04-08
 

package/dist/app-builder/build.js

@@ -196,11 +196,13 @@ const watchApp = (handoff) => __awaiter(void 0, void 0, void 0, function* () {
         runtimeComponentsWatcher: null,
         runtimeConfigurationWatcher: null,
         componentDirectoriesWatcher: null,
+        patternDirectoriesWatcher: null,
     };
     (0, watchers_1.watchPublicDirectory)(handoff, wss, state, chokidarConfig);
     (0, watchers_1.watchRuntimeComponents)(handoff, state, (0, watchers_1.getRuntimeComponentsPathsToWatch)(handoff));
     (0, watchers_1.watchRuntimeConfiguration)(handoff, state);
     (0, watchers_1.watchComponentDirectories)(handoff, state, chokidarConfig);
+    (0, watchers_1.watchPatternDirectories)(handoff, state, chokidarConfig);
     (0, watchers_1.watchGlobalEntries)(handoff, state, chokidarConfig);
     (0, watchers_1.watchPages)(handoff, chokidarConfig);
 });

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/cache/build-cache.js

@@ -136,7 +136,7 @@ function haveGlobalDepsChanged(cached, current) {
  * Gets all file paths that should be tracked for a component
  */
 function getComponentFilePaths(handoff, componentId) {
-    var _a, _b, _c;
+    var _a, _b, _c, _d, _e, _f, _g;
     const runtimeComponent = (_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 ? void 0 : _c[componentId];
     if (!runtimeComponent) {
         return { files: [] };
@@ -169,7 +169,7 @@ function getComponentFilePaths(handoff, componentId) {
                     componentDirs.add((0, path_2.normalizePathForCompare)(path_1.default.dirname(templatePath)));
                 }
             }
-            catch (_d) {
+            catch (_h) {
                 // File doesn't exist, still add to track
                 files.push(templatePath);
                 componentDirs.add((0, path_2.normalizePathForCompare)(path_1.default.dirname(templatePath)));
@@ -202,6 +202,24 @@ function getComponentFilePaths(handoff, componentId) {
     if (matchingConfigPath) {
         files.push(matchingConfigPath);
     }
+    // Include every pattern config file whose declaration references this component.
+    // When a pattern is added or modified, injectPatternPreviews injects new
+    // __pattern_* synthetic preview keys onto the referenced component, changing
+    // what processComponents must render. Without tracking these files here, the
+    // cache would incorrectly consider the component unchanged and skip the preview
+    // rebuild, leaving buildPatterns unable to find the required HTML fragments.
+    const runtimePatterns = (_f = (_e = (_d = handoff.runtimeConfig) === null || _d === void 0 ? void 0 : _d.entries) === null || _e === void 0 ? void 0 : _e.patterns) !== null && _f !== void 0 ? _f : {};
+    for (const configPath of configPaths) {
+        const entry = handoff.getConfigFileEntry(configPath);
+        if ((entry === null || entry === void 0 ? void 0 : entry.kind) !== 'pattern')
+            continue;
+        const pattern = runtimePatterns[entry.entityId];
+        if (!pattern)
+            continue;
+        if ((_g = pattern.components) === null || _g === void 0 ? void 0 : _g.some((ref) => ref.id === componentId)) {
+            files.push(configPath);
+        }
+    }
     return { files, templateDir };
 }
 /**

package/dist/config/runtime.js

@@ -220,7 +220,12 @@ const initRuntimeConfig = (handoff) => {
                 });
             }
             catch (err) {
-                logger_1.Logger.error(`Failed to read or parse pattern config: ${resolvedPatternConfigPath}`, err);
+                // Treat as a warning rather than an error: the file may be empty or
+                // mid-edit. It is already tracked in configFiles above, so
+                // watchRuntimeConfiguration will pick it up once the file is saved
+                // with valid content.
+                logger_1.Logger.warn(`Pattern config skipped (incomplete or invalid) — will retry on next save: ${resolvedPatternConfigPath}`);
+                logger_1.Logger.debug(`Pattern parse detail:`, err);
                 continue;
             }
             configFileIndex.set((0, path_2.normalizePathForCompare)(resolvedPatternConfigPath), { kind: 'pattern', entityId: pattern.id });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "handoff-app",
-  "version": "1.2.2-6",
+  "version": "1.2.2",
   "description": "Automated documentation toolchain for building client side documentation from figma",
   "author ": {
     "name": "Convertiv",

package/src/app/components/Component/ComponentLists.tsx

@@ -76,114 +76,114 @@ export const ComponentList = ({
   return (
     <TooltipProvider delayDuration={0}>
       <div className="mx-auto w-full mb-4">
-      <div className="flex justify-between bg-accent rounded-xl mb-8">
-        <div className="mr-auto flex items-center gap-3 bg-accent p-2.5 rounded-md">
-          <div className="relative">
-            <Search className="absolute left-3 top-1/2 -translate-y-1/2 h-3.5 w-3.5 text-gray-400" />
-            <Input
-              type="text"
-              placeholder="Search components..."
-              className="rounded-md pl-9 pr-3 py-1 text-sm border-none shadow-none"
-              onChange={e => setSearch(e.currentTarget.value)}
-              aria-label="Search components"
-              style={{ minWidth: 200 }}
-
-            />
-          </div>
+        <div className="flex justify-between bg-accent rounded-xl mb-8">
+          <div className="mr-auto flex items-center gap-3 bg-accent p-2.5 rounded-md">
+            <div className="relative">
+              <Search className="absolute left-3 top-1/2 -translate-y-1/2 h-3.5 w-3.5 text-gray-400" />
+              <Input
+                type="text"
+                placeholder="Search components..."
+                className="rounded-md pl-9 pr-3 py-1 text-sm border-none shadow-none"
+                onChange={e => setSearch(e.currentTarget.value)}
+                aria-label="Search components"
+                style={{ minWidth: 200 }}
+
+              />
+            </div>
 
-        </div>
-        <div className="flex justify-end p-2.5 gap-2.5">
-          <div className="flex items-center gap-0.5 border border-input bg-background shadow-xs hover:text-accent-foreground p-0.5 rounded-md">
-            <Select
-              value={category}
-              onValueChange={val => {
-                setCategory(val);
-              }}
-              aria-label="Filter by category"
-            >
-              <SelectTrigger className="rounded-md [&_span]:text-xs [&_svg]:ml-2.5 [&_svg]:size-3 py-1 px-2 pl-3 text-sm border-none shadow-none bg-transparent focus:border-blue-400 focus:outline-none">
-                <SelectValue placeholder="All Categories" />
-              </SelectTrigger>
-              <SelectContent>
-                <SelectItem value="all">All Categories</SelectItem>
-                {categories.map((category) => (
-                  <SelectItem key={category} value={category}>
-                    {category}
-                  </SelectItem>
-                ))}
-              </SelectContent>
-            </Select>
-
-            <hr className="h-7 w-px bg-input" />
-
-            <Tooltip>
-              <TooltipTrigger asChild>
-                <Button variant="ghost" className={cn("w-9", groupBy && 'bg-accent text-accent-foreground')} onClick={() => setGroupBy(!groupBy)}>
-                  <Rows className="size-3.5" strokeWidth={1.5} />
-                  <span className="sr-only">Group by category</span>
-                </Button>
-              </TooltipTrigger>
-              <TooltipContent>
-                Group by category
-              </TooltipContent>
-            </Tooltip>
           </div>
-          <ToggleGroup className='flex gap-0.5 border border-input bg-background shadow-xs hover:text-accent-foreground p-0.5 rounded-md' type="single" value={layout} onValueChange={(value) => storeLayout(value)}>
-            <Tooltip>
-              <TooltipTrigger asChild>
-                <ToggleGroupItem className={cn("size-9 py-2 px-2 flex items-center justify-center hover:bg-accent rounded-md", layout === 'grid' && 'bg-accent text-accent-foreground')} value="grid" aria-label="Grid layout" >
-                  <LayoutGrid className="size-3.5" strokeWidth={1.5} />
-                </ToggleGroupItem>
-              </TooltipTrigger>
-              <TooltipContent>
-                Grid layout
-              </TooltipContent>
-            </Tooltip>
-            <Tooltip>
-              <TooltipTrigger asChild>
-                <ToggleGroupItem className={cn("size-9 py-2 px-2 flex items-center justify-center hover:bg-accent rounded-md", layout === 'single' && 'bg-accent text-accent-foreground')} value="single" aria-label="Single column layout" >
-                  <AlignJustify className="size-3.5" strokeWidth={1.5} />
-                </ToggleGroupItem>
-              </TooltipTrigger>
-              <TooltipContent>
-                Column layout
-              </TooltipContent>
-            </Tooltip>
-          </ToggleGroup>
+          <div className="flex justify-end p-2.5 gap-2.5">
+            <div className="flex items-center gap-0.5 border border-input bg-background shadow-xs hover:text-accent-foreground p-0.5 rounded-md">
+              <Select
+                value={category}
+                onValueChange={val => {
+                  setCategory(val);
+                }}
+                aria-label="Filter by category"
+              >
+                <SelectTrigger className="rounded-md [&_span]:text-xs [&_svg]:ml-2.5 [&_svg]:size-3 py-1 px-2 pl-3 text-sm border-none shadow-none bg-transparent focus:border-blue-400 focus:outline-none">
+                  <SelectValue placeholder="All Categories" />
+                </SelectTrigger>
+                <SelectContent>
+                  <SelectItem value="all">All Categories</SelectItem>
+                  {categories.filter((category) => category !== '').map((category) => (
+                    <SelectItem key={category} value={category}>
+                      {category}
+                    </SelectItem>
+                  ))}
+                </SelectContent>
+              </Select>
+
+              <hr className="h-7 w-px bg-input" />
+
+              <Tooltip>
+                <TooltipTrigger asChild>
+                  <Button variant="ghost" className={cn("w-9", groupBy && 'bg-accent text-accent-foreground')} onClick={() => setGroupBy(!groupBy)}>
+                    <Rows className="size-3.5" strokeWidth={1.5} />
+                    <span className="sr-only">Group by category</span>
+                  </Button>
+                </TooltipTrigger>
+                <TooltipContent>
+                  Group by category
+                </TooltipContent>
+              </Tooltip>
+            </div>
+            <ToggleGroup className='flex gap-0.5 border border-input bg-background shadow-xs hover:text-accent-foreground p-0.5 rounded-md' type="single" value={layout} onValueChange={(value) => storeLayout(value)}>
+              <Tooltip>
+                <TooltipTrigger asChild>
+                  <ToggleGroupItem className={cn("size-9 py-2 px-2 flex items-center justify-center hover:bg-accent rounded-md", layout === 'grid' && 'bg-accent text-accent-foreground')} value="grid" aria-label="Grid layout" >
+                    <LayoutGrid className="size-3.5" strokeWidth={1.5} />
+                  </ToggleGroupItem>
+                </TooltipTrigger>
+                <TooltipContent>
+                  Grid layout
+                </TooltipContent>
+              </Tooltip>
+              <Tooltip>
+                <TooltipTrigger asChild>
+                  <ToggleGroupItem className={cn("size-9 py-2 px-2 flex items-center justify-center hover:bg-accent rounded-md", layout === 'single' && 'bg-accent text-accent-foreground')} value="single" aria-label="Single column layout" >
+                    <AlignJustify className="size-3.5" strokeWidth={1.5} />
+                  </ToggleGroupItem>
+                </TooltipTrigger>
+                <TooltipContent>
+                  Column layout
+                </TooltipContent>
+              </Tooltip>
+            </ToggleGroup>
+          </div>
         </div>
-      </div>
 
-      {groupBy ? (
-        <>
-          {Object.keys(groupedList).map((group) => {
-            return (
-              <div key={`group-${group}`} className="mb-8">
-                <HeadersType.H3 className="mb-4 text-lg font-medium border-b border-gray-200 pb-2">{group}</HeadersType.H3>
-                <div
-                  className={cn(
-                    'grid',
-                    layout === 'grid' ? 'grid-cols-1 gap-10 min-[800px]:grid-cols-2 lg:grid-cols-3 2xl:grid-cols-4' : 'grid-cols-1 gap-2'
-                  )}
-                >
-                  {groupedList[group].map((component) => {
-                    return <ComponentsPageCard key={`component-${component.id}`} component={component} layout={layout} />;
-                  })}
+        {groupBy ? (
+          <>
+            {Object.keys(groupedList).map((group) => {
+              return (
+                <div key={`group-${group}`} className="mb-8">
+                  <HeadersType.H3 className="mb-4 text-lg font-medium border-b border-gray-200 pb-2">{group}</HeadersType.H3>
+                  <div
+                    className={cn(
+                      'grid',
+                      layout === 'grid' ? 'grid-cols-1 gap-10 min-[800px]:grid-cols-2 lg:grid-cols-3 2xl:grid-cols-4' : 'grid-cols-1 gap-2'
+                    )}
+                  >
+                    {groupedList[group].map((component) => {
+                      return <ComponentsPageCard key={`component-${component.id}`} component={component} layout={layout} />;
+                    })}
+                  </div>
                 </div>
-              </div>
-            );
+              );
+            })}
+          </>
+        ) : (
+          <div
+            className={cn(
+              'grid',
+              layout === 'grid' ? 'grid-cols-1 gap-10 min-[800px]:grid-cols-2 lg:grid-cols-3 2xl:grid-cols-4' : 'grid-cols-1 gap-2'
+            )}
+          >            {list.map((component) => {
+            return <ComponentsPageCard key={`component-${component.id}`} component={component} layout={layout} />;
           })}
-        </>
-      ) : (
-        <div
-          className={cn(
-            'grid',
-            layout === 'grid' ? 'grid-cols-1 gap-10 min-[800px]:grid-cols-2 lg:grid-cols-3 2xl:grid-cols-4' : 'grid-cols-1 gap-2'
-          )}
-        >            {list.map((component) => {
-          return <ComponentsPageCard key={`component-${component.id}`} component={component} layout={layout} />;
-        })}
-        </div>
-      )}
+          </div>
+        )}
       </div>
     </TooltipProvider>
   );

package/src/app/components/NotFound.tsx

@@ -0,0 +1,24 @@
+import React from 'react';
+
+interface NotFoundProps {
+  title?: string;
+  description?: React.ReactNode;
+  linkHref?: string;
+  linkLabel?: string;
+}
+
+const NotFound: React.FC<NotFoundProps> = () => {
+  return (
+    <div className="flex flex-col items-center">
+      <div className="mb-2 text-7xl font-bold text-gray-800 dark:text-white">404</div>
+      <h1 className="mb-4 text-2xl font-semibold text-gray-700 dark:text-gray-300">Oops! Page not found.</h1>
+      <p className="mb-6 max-w-md text-center text-gray-500 dark:text-gray-400">
+        This page doesn&rsquo;t exist or has been moved.
+        <br />
+        Please check the URL or return to the homepage.
+      </p>
+    </div>
+  );
+};
+
+export default NotFound;

package/src/app/pages/[...slug]/index.tsx

@@ -1,7 +1,7 @@
 import { GetStaticProps } from 'next';
 import Head from 'next/head';
-import Link from 'next/link';
 import { useRef } from 'react';
+import NotFound from '../../components/NotFound';
 import ReactMarkdown from 'react-markdown';
 import rehypeRaw from 'rehype-raw';
 import remarkGfm from 'remark-gfm';
@@ -48,21 +48,7 @@ export default function DocCatchAllPage({ content, menu, metadata, current, conf
           <title>404 - Page Not Found</title>
           <meta name="description" content="Page Not Found" />
         </Head>
-        <div className="flex flex-col items-center">
-          <div className="mb-2 text-7xl font-bold text-gray-800 dark:text-white">404</div>
-          <h1 className="mb-4 text-2xl font-semibold text-gray-700 dark:text-gray-300">Oops! Page not found.</h1>
-          <p className="mb-6 max-w-md text-center text-gray-500 dark:text-gray-400">
-            Sorry, the page you are looking for does not exist or has been moved.
-            <br />
-            Please check the URL or return to the homepage.
-          </p>
-          <Link
-            href="/"
-            className="rounded-md bg-blue-600 px-6 py-2 font-medium text-white shadow-md transition-colors duration-200 hover:bg-blue-700"
-          >
-            Go Home
-          </Link>
-        </div>
+        <NotFound />
       </div>
     );
   }

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

@@ -5,6 +5,7 @@ import React, { useCallback, useEffect, useState } from 'react';
 import ReactMarkdown from 'react-markdown';
 import rehypeRaw from 'rehype-raw';
 import Layout from '../../../../components/Layout/Main';
+import NotFound from '../../../../components/NotFound';
 import { MarkdownComponents } from '../../../../components/Markdown/MarkdownComponents';
 import PrevNextNav from '../../../../components/Navigation/PrevNextNav';
 import HeadersType from '../../../../components/Typography/Headers';
@@ -130,6 +131,7 @@ export const getStaticProps = async (context: { params: IParams }) => {
 const PatternPage = ({ menu, metadata, current, id, config, previousPattern, nextPattern }: PatternPageProps) => {
   const [pattern, setPattern] = useState<PatternListObject | undefined>(undefined);
   const [fetchError, setFetchError] = useState<string | undefined>(undefined);
+  const [patternNotFound, setPatternNotFound] = useState(false);
   const [iframeHeight, setIframeHeight] = useState('400px');
   const iframeRef = React.useRef<HTMLIFrameElement>(null);
 
@@ -145,13 +147,20 @@ const PatternPage = ({ menu, metadata, current, id, config, previousPattern, nex
     const controller = new AbortController();
     setPattern(undefined);
     setFetchError(undefined);
+    setPatternNotFound(false);
 
     fetch(`${normalizedBasePath}/api/pattern/${id}.json`, { signal: controller.signal })
       .then((res) => {
+        if (res.status === 404) {
+          setPatternNotFound(true);
+          return null;
+        }
         if (!res.ok) throw new Error(`Failed to load pattern: ${res.status} ${res.statusText}`);
         return res.json();
       })
-      .then((data) => setPattern(data as PatternListObject))
+      .then((data) => {
+        if (data) setPattern(data as PatternListObject);
+      })
       .catch((err) => {
         if (err.name !== 'AbortError') {
           setFetchError(err instanceof Error ? err.message : 'Failed to load pattern data.');
@@ -167,7 +176,27 @@ const PatternPage = ({ menu, metadata, current, id, config, previousPattern, nex
     }
   }, []);
 
-  if (fetchError) return <p className="p-4 text-red-500">{fetchError}</p>;
+  if (patternNotFound) {
+    return (
+      <Layout config={config} menu={menu} current={current} metadata={{ ...metadata, title: '404 - Page Not Found', metaTitle: '404 - Page Not Found' }}>
+        <div className="flex min-h-[60vh] flex-col items-center justify-center">
+          <NotFound />
+        </div>
+      </Layout>
+    );
+  }
+
+  if (fetchError) {
+    return (
+      <Layout config={config} menu={menu} current={current} metadata={metadata}>
+        <div className="flex min-h-[60vh] flex-col items-center justify-center gap-2">
+          <p className="text-lg font-semibold text-gray-700 dark:text-gray-300">Something went wrong</p>
+          <p className="text-sm text-red-500">{fetchError}</p>
+        </div>
+      </Layout>
+    );
+  }
+
   if (!pattern) return <p>Loading...</p>;
 
   return (

package/src/app-builder/build.ts

@@ -17,6 +17,7 @@ import {
   watchComponentDirectories,
   watchGlobalEntries,
   watchPages,
+  watchPatternDirectories,
   watchPublicDirectory,
   watchRuntimeComponents,
   watchRuntimeConfiguration,
@@ -224,12 +225,14 @@ export const watchApp = async (handoff: Handoff): Promise<void> => {
     runtimeComponentsWatcher: null,
     runtimeConfigurationWatcher: null,
     componentDirectoriesWatcher: null,
+    patternDirectoriesWatcher: null,
   };
 
   watchPublicDirectory(handoff, wss, state, chokidarConfig);
   watchRuntimeComponents(handoff, state, getRuntimeComponentsPathsToWatch(handoff));
   watchRuntimeConfiguration(handoff, state);
   watchComponentDirectories(handoff, state, chokidarConfig);
+  watchPatternDirectories(handoff, state, chokidarConfig);
   watchGlobalEntries(handoff, state, chokidarConfig);
   watchPages(handoff, chokidarConfig);
 };

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/cache/build-cache.ts

@@ -226,6 +226,23 @@ export function getComponentFilePaths(handoff: Handoff, componentId: string): {
     files.push(matchingConfigPath);
   }
 
+  // Include every pattern config file whose declaration references this component.
+  // When a pattern is added or modified, injectPatternPreviews injects new
+  // __pattern_* synthetic preview keys onto the referenced component, changing
+  // what processComponents must render. Without tracking these files here, the
+  // cache would incorrectly consider the component unchanged and skip the preview
+  // rebuild, leaving buildPatterns unable to find the required HTML fragments.
+  const runtimePatterns = handoff.runtimeConfig?.entries?.patterns ?? {};
+  for (const configPath of configPaths) {
+    const entry = handoff.getConfigFileEntry(configPath);
+    if (entry?.kind !== 'pattern') continue;
+    const pattern = runtimePatterns[entry.entityId];
+    if (!pattern) continue;
+    if (pattern.components?.some((ref) => ref.id === componentId)) {
+      files.push(configPath);
+    }
+  }
+
   return { files, templateDir };
 }
 

package/src/config/runtime.ts

@@ -284,7 +284,12 @@ export const initRuntimeConfig = (handoff: HandoffContext): [runtimeConfig: Runt
           fallbackId: patternBaseName,
         });
       } catch (err) {
-        Logger.error(`Failed to read or parse pattern config: ${resolvedPatternConfigPath}`, err);
+        // Treat as a warning rather than an error: the file may be empty or
+        // mid-edit. It is already tracked in configFiles above, so
+        // watchRuntimeConfiguration will pick it up once the file is saved
+        // with valid content.
+        Logger.warn(`Pattern config skipped (incomplete or invalid) — will retry on next save: ${resolvedPatternConfigPath}`);
+        Logger.debug(`Pattern parse detail:`, err);
         continue;
       }
 

package/handoff.config.js

@@ -1,90 +0,0 @@
-/** @type {import('handoff-app').Config} */
-const path = require('path');
-module.exports = {
-  // Set your Figma project ID here or in the environment variable HANDOFF_FIGMA_PROJECT_ID
-  figma_project_id: null,
-  // Set the output directory for the exported components
-  exportsOutputDirectory: 'exported',
-  // Set the output directory for the sites
-  sitesOutputDirectory: 'out',
-  // These settings control the behavior of the application
-  app: {
-    // Set the theme for the application
-    theme: 'default',
-    // Set the title for the application
-    title: 'Handoff Design System',
-    // Set the client for the application, used in the footer
-    client: 'Handoff Technologies',
-    // Set the Google Tag Manager ID to add GTM scripts
-    google_tag_manager: null,
-    // Set the attribution for the application
-    attribution: true, // Should we remove this?
-    // Set the type copy for the typeography page
-    type_copy: 'Almost before we knew it, we had left the ground.',
-    // Set the type sort for the typeography page
-    type_sort: [
-      'Heading 1',
-      'Heading 2',
-      'Heading 3',
-      'Heading 4',
-      'Heading 5',
-      'Heading 6',
-      'Paragraph',
-      'Subheading',
-      'Blockquote',
-      'Input Labels',
-      'Link',
-    ],
-    // Set the color sort for the color page
-    color_sort: ['primary', 'secondary', 'extra', 'system'],
-    // Set the component sort for the component page
-    component_sort: ['primary', 'secondary', 'transparent'],
-    // Set the base path for the application
-    base_path: '',
-    // Set the breakpoints for the application
-    breakpoints: {
-      sm: { size: 576, name: 'Small' },
-      md: { size: 768, name: 'Medium' },
-      lg: { size: 992, name: 'Large' },
-      xl: { size: 1200, name: 'Extra Large' },
-    },
-    // Set the ports for the application
-    ports: { app: 3000, websocket: 3001 },
-  },
-  // These are the entry points used to compile the target application
-  entries: {
-    scss: './sass/main.scss',
-    js: './js/main.js',
-    bundle: './js/main.js',
-    //components: ['./test_components'],
-    //patterns: ['./test_patterns'],
-  },
-  // These are the asset zip file download links
-  assets_zip_links: {
-    icons: null,
-    logos: null,
-  },
-  // Hooks allow you to override the default behavior of the application
-  hooks: {
-    // Alter the vite css build config
-    cssBuildConfig: (config) => {
-      return config;
-    },
-    // Validate each component before it is exported
-    validateComponent: (component) => {
-      return {};
-    },
-    // Alter the vite client build config
-    clientBuildConfig: (config) => {
-      return config;
-    },
-    // Alter the vite html build config
-    htmlBuildConfig: (config) => {
-      return config;
-    },
-    // Alter the vite js build config
-    jsBuildConfig: (config) => {
-      return config;
-    },
-  },
-};