handoff-app 1.1.0 → 1.1.1

package/Changelog.md

@@ -6,6 +6,14 @@ 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.1.1] - 2026-03-12
+
+This patch release focuses on Windows stabilization and consistency across environments.
+
+It includes targeted fixes to reduce platform-specific issues in local development and documentation rendering, especially around path handling, routing/navigation behavior, and runtime update detection. These changes aim to make behavior on Windows align more closely with Mac and Linux, with no intended breaking changes.
+
+Also includes a fallback for components with empty previews definitions, preventing preview generation failures during builds.
+
 ## \[1.1.0] - 2026-03-05
 
 This release introduces two major new features. First, handoff now can do automatic

package/dist/app-builder/build.js

@@ -25,6 +25,7 @@ const client_config_1 = require("./client-config");
 const paths_1 = require("./paths");
 const watchers_1 = require("./watchers");
 const websocket_1 = require("./websocket");
+const escapeForSingleQuotedJsString = (value) => value.replace(/\\/g, '\\\\').replace(/'/g, "\\'");
 /**
  * Performs cleanup of the application directory by removing the existing app directory if it exists.
  */
@@ -57,8 +58,7 @@ const initializeProjectApp = (handoff) => __awaiter(void 0, void 0, void 0, func
         yield fs_extra_1.default.copy(customThemePath, destPath, { overwrite: true });
         logger_1.Logger.success(`Custom theme.css loaded`);
     }
-    // Prepare project app configuration
-    // Warning: Regex replacement is fragile and depends on exact formatting in next.config.mjs
+    // Prepare project app configuration using stable placeholder replacement.
     const handoffProjectId = handoff.getProjectId();
     const handoffAppBasePath = (_a = handoff.config.app.base_path) !== null && _a !== void 0 ? _a : '';
     const handoffWorkingPath = path_1.default.resolve(handoff.workingPath);
@@ -67,15 +67,24 @@ const initializeProjectApp = (handoff) => __awaiter(void 0, void 0, void 0, func
     const nextConfigPath = path_1.default.resolve(srcPath, 'next.config.mjs');
     const targetPath = path_1.default.resolve(appPath, 'next.config.mjs');
     const handoffWebsocketPort = (_c = (_b = handoff.config.app.ports) === null || _b === void 0 ? void 0 : _b.websocket) !== null && _c !== void 0 ? _c : 3001;
-    const nextConfigContent = (yield fs_extra_1.default.readFile(nextConfigPath, 'utf-8'))
-        .replace(/basePath:\s+''/g, `basePath: '${handoffAppBasePath}'`)
-        .replace(/HANDOFF_PROJECT_ID:\s+''/g, `HANDOFF_PROJECT_ID: '${handoffProjectId}'`)
-        .replace(/HANDOFF_APP_BASE_PATH:\s+''/g, `HANDOFF_APP_BASE_PATH: '${handoffAppBasePath}'`)
-        .replace(/HANDOFF_WORKING_PATH:\s+''/g, `HANDOFF_WORKING_PATH: '${handoffWorkingPath}'`)
-        .replace(/HANDOFF_MODULE_PATH:\s+''/g, `HANDOFF_MODULE_PATH: '${handoffModulePath}'`)
-        .replace(/HANDOFF_EXPORT_PATH:\s+''/g, `HANDOFF_EXPORT_PATH: '${handoffExportPath}'`)
-        .replace(/HANDOFF_WEBSOCKET_PORT:\s+''/g, `HANDOFF_WEBSOCKET_PORT: '${handoffWebsocketPort}'`)
-        .replace(/%HANDOFF_MODULE_PATH%/g, handoffModulePath);
+    const escapedAppBasePath = escapeForSingleQuotedJsString(handoffAppBasePath);
+    const escapedProjectId = escapeForSingleQuotedJsString(handoffProjectId);
+    const escapedWorkingPath = escapeForSingleQuotedJsString(handoffWorkingPath);
+    const escapedModulePath = escapeForSingleQuotedJsString(handoffModulePath);
+    const escapedExportPath = escapeForSingleQuotedJsString(handoffExportPath);
+    const escapedWebsocketPort = escapeForSingleQuotedJsString(String(handoffWebsocketPort));
+    const placeholderValues = {
+        '%HANDOFF_PROJECT_ID%': escapedProjectId,
+        '%HANDOFF_APP_BASE_PATH%': escapedAppBasePath,
+        '%HANDOFF_WORKING_PATH%': escapedWorkingPath,
+        '%HANDOFF_MODULE_PATH%': escapedModulePath,
+        '%HANDOFF_EXPORT_PATH%': escapedExportPath,
+        '%HANDOFF_WEBSOCKET_PORT%': escapedWebsocketPort,
+    };
+    let nextConfigContent = yield fs_extra_1.default.readFile(nextConfigPath, 'utf-8');
+    for (const [placeholder, value] of Object.entries(placeholderValues)) {
+        nextConfigContent = nextConfigContent.split(placeholder).join(value);
+    }
     yield fs_extra_1.default.writeFile(targetPath, nextConfigContent);
     return appPath;
 });

package/dist/app-builder/watchers.js

@@ -43,6 +43,7 @@ const css_1 = require("../transformers/preview/component/css");
 const javascript_1 = require("../transformers/preview/component/javascript");
 const builder_1 = __importStar(require("../transformers/preview/component/builder"));
 const logger_1 = require("../utils/logger");
+const path_2 = require("../utils/path");
 const client_config_1 = require("./client-config");
 const paths_1 = require("./paths");
 /**
@@ -145,11 +146,6 @@ const watchGlobalEntries = (handoff, state, chokidarConfig) => {
     const pathsToWatch = [...scssPathsToWatch, ...jsPathsToWatch];
     if (pathsToWatch.length === 0)
         return;
-    const isPathInside = (filePath, parentPath) => {
-        const normalizedFilePath = path_1.default.resolve(filePath);
-        const normalizedParentPath = path_1.default.resolve(parentPath);
-        return normalizedFilePath === normalizedParentPath || normalizedFilePath.startsWith(`${normalizedParentPath}${path_1.default.sep}`);
-    };
     chokidar_1.default.watch(pathsToWatch, chokidarConfig).on('all', (event, file) => __awaiter(void 0, void 0, void 0, function* () {
         switch (event) {
             case 'add':
@@ -159,8 +155,8 @@ const watchGlobalEntries = (handoff, state, chokidarConfig) => {
                     state.debounce = true;
                     try {
                         logger_1.Logger.warn('Global entry changed. Rebuilding bundles and components...');
-                        const shouldRebuildMainCss = !!scssEntry && scssPathsToWatch.some((watchPath) => isPathInside(file, watchPath));
-                        const shouldRebuildMainJs = !!jsEntry && jsPathsToWatch.some((watchPath) => isPathInside(file, watchPath));
+                        const shouldRebuildMainCss = !!scssEntry && scssPathsToWatch.some((watchPath) => (0, path_2.isPathInside)(file, watchPath));
+                        const shouldRebuildMainJs = !!jsEntry && jsPathsToWatch.some((watchPath) => (0, path_2.isPathInside)(file, watchPath));
                         if (shouldRebuildMainCss) {
                             yield (0, css_1.buildMainCss)(handoff);
                         }
@@ -228,11 +224,14 @@ const watchRuntimeComponents = (handoff, state, runtimeComponentPathsToWatch) =>
     }
     if (runtimeComponentPathsToWatch.size > 0) {
         const pathsToWatch = Array.from(runtimeComponentPathsToWatch.keys());
+        const runtimeComponentEntryTypeByPath = new Map(Array.from(runtimeComponentPathsToWatch.entries()).map(([watchPath, entryType]) => [(0, path_2.normalizePathForCompare)(watchPath), entryType]));
+        const configFileSet = new Set(handoff.getConfigFilePaths().map((configPath) => (0, path_2.normalizePathForCompare)(configPath)));
         state.runtimeComponentsWatcher = chokidar_1.default.watch(pathsToWatch, {
             ignoreInitial: true,
         });
         state.runtimeComponentsWatcher.on('all', (event, file) => __awaiter(void 0, void 0, void 0, function* () {
-            if (handoff.getConfigFilePaths().includes(file)) {
+            const normalizedFile = (0, path_2.normalizePathForCompare)(file);
+            if (configFileSet.has(normalizedFile)) {
                 return;
             }
             switch (event) {
@@ -242,7 +241,7 @@ const watchRuntimeComponents = (handoff, state, runtimeComponentPathsToWatch) =>
                     if (!state.debounce) {
                         state.debounce = true;
                         try {
-                            const entryType = runtimeComponentPathsToWatch.get(file);
+                            const entryType = runtimeComponentEntryTypeByPath.get(normalizedFile);
                             const segmentToUpdate = entryType ? (0, exports.mapEntryTypeToSegment)(entryType) : undefined;
                             const componentDir = path_1.default.basename(path_1.default.dirname(file));
                             yield (0, builder_1.default)(handoff, componentDir, segmentToUpdate);

package/dist/cache/build-cache.js

@@ -27,6 +27,7 @@ exports.pruneRemovedComponents = pruneRemovedComponents;
 const fs_extra_1 = __importDefault(require("fs-extra"));
 const path_1 = __importDefault(require("path"));
 const logger_1 = require("../utils/logger");
+const path_2 = require("../utils/path");
 const file_state_1 = require("./file-state");
 /** Current cache format version - bump when structure changes */
 const CACHE_VERSION = '1.0.0';
@@ -142,23 +143,17 @@ function getComponentFilePaths(handoff, componentId) {
     }
     const files = [];
     let templateDir;
-    // Find the config file path for this component
-    const configPaths = handoff.getConfigFilePaths();
-    for (const configPath of configPaths) {
-        // Check if this config path belongs to this component
-        if (configPath.includes(componentId)) {
-            files.push(configPath);
-            break;
-        }
-    }
-    // Add entry files
+    const componentDirs = new Set();
+    // Add entry files and infer component directories from resolved entry paths
     const entries = runtimeComponent.entries;
     if (entries) {
         if (entries.js) {
             files.push(entries.js);
+            componentDirs.add((0, path_2.normalizePathForCompare)(path_1.default.dirname(entries.js)));
         }
         if (entries.scss) {
             files.push(entries.scss);
+            componentDirs.add((0, path_2.normalizePathForCompare)(path_1.default.dirname(entries.scss)));
         }
         // Handle both 'template' (singular) and 'templates' (plural) entry types
         const templatePath = entries.template || entries.templates;
@@ -167,17 +162,37 @@ function getComponentFilePaths(handoff, componentId) {
                 const stat = fs_extra_1.default.statSync(templatePath);
                 if (stat.isDirectory()) {
                     templateDir = templatePath;
+                    componentDirs.add((0, path_2.normalizePathForCompare)(templatePath));
                 }
                 else {
                     files.push(templatePath);
+                    componentDirs.add((0, path_2.normalizePathForCompare)(path_1.default.dirname(templatePath)));
                 }
             }
             catch (_d) {
                 // File doesn't exist, still add to track
                 files.push(templatePath);
+                componentDirs.add((0, path_2.normalizePathForCompare)(path_1.default.dirname(templatePath)));
             }
         }
     }
+    // Find the config file path for this component using exact config filename + directory matching.
+    const configPaths = handoff.getConfigFilePaths();
+    const expectedConfigFileNames = new Set([`${componentId}.json`, `${componentId}.js`, `${componentId}.cjs`]);
+    const matchingConfigPath = configPaths.find((configPath) => {
+        const configFileName = path_1.default.basename(configPath);
+        if (!expectedConfigFileNames.has(configFileName)) {
+            return false;
+        }
+        if (componentDirs.size === 0) {
+            return true;
+        }
+        const configDir = (0, path_2.normalizePathForCompare)(path_1.default.dirname(configPath));
+        return componentDirs.has(configDir);
+    });
+    if (matchingConfigPath) {
+        files.push(matchingConfigPath);
+    }
     return { files, templateDir };
 }
 /**

package/dist/cli.js

@@ -19,7 +19,7 @@ class HandoffCliError extends Error {
  * Show the help message
  */
 const showVersion = () => {
-    return 'Handoff App - 1.1.0';
+    return 'Handoff App - 1.1.1';
 };
 /**
  * Define a CLI error

package/dist/transformers/plugins/handlebars-previews.js

@@ -131,6 +131,16 @@ function handlebarsPreviewsPlugin(componentData, documentationComponents, handof
                 }
                 // Process component instances from documentation
                 processComponentInstances(componentData, documentationComponents);
+                if (!componentData.previews || Object.keys(componentData.previews).length === 0) {
+                    logger_1.Logger.warn(`No previews defined for ${componentId}; using default preview values.`);
+                    componentData.previews = {
+                        default: {
+                            title: 'Default',
+                            values: {},
+                            url: '',
+                        },
+                    };
+                }
                 const generatedPreviews = {};
                 // Generate previews for each variation
                 for (const previewKey in componentData.previews) {
@@ -153,7 +163,8 @@ function handlebarsPreviewsPlugin(componentData, documentationComponents, handof
                 componentData.format = PLUGIN_CONSTANTS.OUTPUT_FORMAT;
                 componentData.preview = '';
                 componentData.code = (0, html_1.trimPreview)(templateContent);
-                componentData.html = (0, html_1.trimPreview)(generatedPreviews[Object.keys(generatedPreviews)[0]]);
+                const firstGeneratedPreview = Object.values(generatedPreviews)[0];
+                componentData.html = (0, html_1.trimPreview)(firstGeneratedPreview !== null && firstGeneratedPreview !== void 0 ? firstGeneratedPreview : templateContent);
             });
         },
     };

package/dist/transformers/preview/component/builder.js

@@ -66,6 +66,19 @@ var ComponentSegment;
     ComponentSegment["Previews"] = "previews";
     ComponentSegment["Validation"] = "validation";
 })(ComponentSegment || (exports.ComponentSegment = ComponentSegment = {}));
+const ensureDefaultPreview = (data) => {
+    if (!data)
+        return;
+    if (!data.previews || Object.keys(data.previews).length === 0) {
+        data.previews = {
+            default: {
+                title: 'Default',
+                values: {},
+                url: '',
+            },
+        };
+    }
+};
 /**
  * Returns a normalized build plan describing which component segments need rebuilding.
  *
@@ -200,7 +213,7 @@ function processComponents(handoff, id, segmentToProcess, options) {
             // those will override this default (standard "config overrides defaults" behavior).
             if (!restMetadata.figmaComponentId) {
                 componentDefaults.previews = {
-                    generic: {
+                    default: {
                         title: 'Default',
                         values: {},
                         url: '',
@@ -246,6 +259,8 @@ function processComponents(handoff, id, segmentToProcess, options) {
                     data.properties = existingData.properties;
                 }
             }
+            // Components should always have at least one preview variation.
+            ensureDefaultPreview(data);
             // Build JS if needed (new build, validation missing, or explicit segment request).
             if (buildPlan.js) {
                 data = yield (0, javascript_1.default)(data, handoff);

package/dist/transformers/utils/html.js

@@ -21,9 +21,21 @@ const prettier_1 = __importDefault(require("prettier"));
  * @returns Trimmed HTML content
  */
 const trimPreview = (preview) => {
-    const bodyEl = (0, node_html_parser_1.parse)(preview).querySelector('body');
-    const code = bodyEl ? bodyEl.innerHTML.trim() : preview;
-    return code;
+    if (typeof preview !== 'string') {
+        return '';
+    }
+    const normalizedPreview = preview.trim();
+    if (!normalizedPreview) {
+        return '';
+    }
+    try {
+        const bodyEl = (0, node_html_parser_1.parse)(normalizedPreview).querySelector('body');
+        return bodyEl ? bodyEl.innerHTML.trim() : normalizedPreview;
+    }
+    catch (_a) {
+        // Keep build resilient if parser fails on malformed HTML.
+        return normalizedPreview;
+    }
 };
 exports.trimPreview = trimPreview;
 /**

package/dist/utils/path.d.ts

@@ -4,3 +4,18 @@
  * @returns A filesystem-safe string suitable for use as a directory name
  */
 export declare function generateFilesystemSafeId(workingPath: string): string;
+/**
+ * Normalize a filesystem path for cross-platform string comparison.
+ * - Resolves to absolute path
+ * - Normalizes separators to forward slashes
+ * - Lowercases on Windows where paths are case-insensitive
+ */
+export declare function normalizePathForCompare(inputPath: string): string;
+/**
+ * True when both paths resolve to the same normalized filesystem path.
+ */
+export declare function arePathsEqual(pathA: string, pathB: string): boolean;
+/**
+ * True when childPath is equal to or within parentPath.
+ */
+export declare function isPathInside(childPath: string, parentPath: string): boolean;

package/dist/utils/path.js

@@ -1,6 +1,13 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.generateFilesystemSafeId = generateFilesystemSafeId;
+exports.normalizePathForCompare = normalizePathForCompare;
+exports.arePathsEqual = arePathsEqual;
+exports.isPathInside = isPathInside;
+const path_1 = __importDefault(require("path"));
 /**
  * Generates a filesystem-safe directory name from an absolute path
  * @param workingPath - The absolute working path to transform
@@ -26,3 +33,27 @@ function generateFilesystemSafeId(workingPath) {
     }
     return safeId;
 }
+/**
+ * Normalize a filesystem path for cross-platform string comparison.
+ * - Resolves to absolute path
+ * - Normalizes separators to forward slashes
+ * - Lowercases on Windows where paths are case-insensitive
+ */
+function normalizePathForCompare(inputPath) {
+    const normalized = path_1.default.resolve(inputPath).replace(/\\/g, '/');
+    return process.platform === 'win32' ? normalized.toLowerCase() : normalized;
+}
+/**
+ * True when both paths resolve to the same normalized filesystem path.
+ */
+function arePathsEqual(pathA, pathB) {
+    return normalizePathForCompare(pathA) === normalizePathForCompare(pathB);
+}
+/**
+ * True when childPath is equal to or within parentPath.
+ */
+function isPathInside(childPath, parentPath) {
+    const normalizedChild = normalizePathForCompare(childPath);
+    const normalizedParent = normalizePathForCompare(parentPath);
+    return normalizedChild === normalizedParent || normalizedChild.startsWith(`${normalizedParent}/`);
+}

package/package.json

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

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

@@ -8,7 +8,7 @@ import HeadersType from '../Typography/Headers';
 import { Button } from '../ui/button';
 import { Input } from '../ui/input';
 import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from '../ui/select';
-import { Tooltip, TooltipContent, TooltipTrigger } from '../ui/tooltip';
+import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from '../ui/tooltip';
 import { Metadata } from '../util';
 
 interface ComponentMetadata extends Metadata {
@@ -74,7 +74,8 @@ export const ComponentList = ({
   if (!title) title = 'Components';
   if (!description) description = 'Self-contained reusable UI elements that can be used to build larger blocks or design patterns.';
   return (
-    <div className="mx-auto w-full mb-4">
+    <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">
@@ -183,8 +184,8 @@ export const ComponentList = ({
         })}
         </div>
       )}
-    </div>
-
+      </div>
+    </TooltipProvider>
   );
 };
 

package/src/app/components/Navigation/MainNav.tsx

@@ -31,13 +31,12 @@ export function MainNav() {
                     <NavigationMenuLink className={navigationMenuTriggerStyle()} asChild>
                       <Link
                         href={section.path}
-                        passHref
                         className={cn(
                           'block select-none space-y-1 rounded-sm p-3 leading-none no-underline outline-hidden transition-colors hover:bg-accent hover:text-accent-foreground focus:bg-accent focus:text-accent-foreground'
                         )}
                         {...(isActive ? { 'data-active': 'true' } : {})}
                       >
-                        {section.title} {isActive}
+                        {section.title}
                       </Link>
                     </NavigationMenuLink>
                   </>
@@ -51,11 +50,10 @@ export function MainNav() {
                   <NavigationMenuLink className={navigationMenuTriggerStyle()} asChild>
                     <Link
                       href={section.path}
-                      passHref
-                      legacyBehavior
                       className="block select-none space-y-1 rounded-sm p-3 leading-none no-underline outline-hidden transition-colors hover:bg-accent hover:text-accent-foreground focus:bg-accent focus:text-accent-foreground"
+                      {...(isActive ? { 'data-active': 'true' } : {})}
                     >
-                      <div className="text-sm leading-none">{section.title}</div>
+                      <span className="text-sm leading-none">{section.title}</span>
                     </Link>
                   </NavigationMenuLink>
                 )}

package/src/app/components/Navigation/SideNav.tsx

@@ -30,19 +30,16 @@ import {
   SidebarMenuSub,
   SidebarSeparator,
 } from '../../components/ui/sidebar';
+import { normalizePathForMatch, toAbsolutePath } from '../../lib/utils';
 import { SectionLink } from '../util';
 
-const trimSlashes = (input: string): string => {
-  return input.replace(/^\/+|\/+$/g, '');
-};
-
 const NormalMenuItem = ({ title, icon, path }) => {
   const router = useRouter();
-  const isActive = trimSlashes(path) === trimSlashes(router.asPath);
+  const isActive = normalizePathForMatch(path) === normalizePathForMatch(router.asPath);
   return (
     <SidebarMenuItem>
       <SidebarMenuButton asChild isActive={isActive}>
-        <a href={`/${path}`} className="gap-3">
+        <a href={toAbsolutePath(path)} className="gap-3">
           <MenuIcon icon={icon} isActive={isActive} />
           <span>{title}</span>
         </a>
@@ -54,7 +51,7 @@ const NormalMenuItem = ({ title, icon, path }) => {
 const CollapsibleMenuItem = ({ title, icon, path, menu }) => {
   const router = useRouter();
   const isActive = menu.some(
-    (item) => trimSlashes(router.asPath).startsWith(trimSlashes(item.path)) || trimSlashes(item.path) === trimSlashes(router.asPath)
+    (item) => normalizePathForMatch(router.asPath).startsWith(normalizePathForMatch(item.path))
   );
   return (
     <Collapsible defaultOpen={isActive} className="group/collapsible">

package/src/app/components/SideNav/Custom.tsx

@@ -1,9 +1,11 @@
 import { usePathname } from 'next/navigation';
+import { normalizePathForMatch, toAbsolutePath } from '../../lib/utils';
 import NavLink from '../NavLink';
 import { SectionLink } from '../util';
 
 const CustomNav = ({ menu }: { menu: SectionLink }) => {
   const pathname = usePathname();
+  const normalizedPathname = normalizePathForMatch(pathname ?? '');
   return (
     <nav className="c-sidenav">
       <ul>
@@ -13,14 +15,14 @@ const CustomNav = ({ menu }: { menu: SectionLink }) => {
               <small>{item.title}</small>
             ) : (
               <>
-                <NavLink href={`/${item.path}`}>
+                <NavLink href={toAbsolutePath(item.path)}>
                   {item.title}
                 </NavLink>
                 {item.menu && (
-                  <ul className={`c-sidenav__sub${pathname.includes(item.path) ? ' is-active' : ''}`}>
+                  <ul className={`c-sidenav__sub${normalizedPathname.startsWith(normalizePathForMatch(item.path)) ? ' is-active' : ''}`}>
                     {item.menu.map((subItem) => (
                       <li key={subItem.path}>
-                        <NavLink key={subItem.path} href={`/${subItem.path}`} className="c-sidenav__sub-item">
+                        <NavLink key={subItem.path} href={toAbsolutePath(subItem.path)} className="c-sidenav__sub-item">
                           {subItem.title}
                         </NavLink>
                       </li>

package/src/app/components/ui/mobile-nav.tsx

@@ -1,8 +1,9 @@
 'use client';
 
 import Link from 'next/link';
-import { usePathname, useRouter } from 'next/navigation';
+import { usePathname } from 'next/navigation';
 import * as React from 'react';
+import { normalizePathForMatch, toAbsolutePath } from '../../lib/utils';
 import { SectionLink } from '../util';
 
 import { Button } from './button';
@@ -15,7 +16,7 @@ interface MobileNavProps {
 export function MobileNav({ menu }: MobileNavProps) {
   const [open, setOpen] = React.useState(false);
   const pathname = usePathname();
-  const router = useRouter();
+  const normalizedPathname = normalizePathForMatch(pathname ?? '');
 
   const onOpenChange = React.useCallback((open: boolean) => {
     setOpen(open);
@@ -52,24 +53,26 @@ export function MobileNav({ menu }: MobileNavProps) {
                   ) : (
                     <>
                       <Link
-                        href={`/${item.path}`}
+                        href={toAbsolutePath(item.path)}
                         className="text-[1.15rem]"
                         onClick={() => {
-                          router.push(`/${item.path}`);
                           setOpen(false);
                         }}
                       >
                         {item.title}
                       </Link>
                       {item.menu && (
-                        <ul className={`ml-4 mt-2 space-y-2${pathname.includes(item.path) ? ' is-active' : ''}`}>
+                        <ul
+                          className={`ml-4 mt-2 space-y-2${
+                            normalizedPathname.startsWith(normalizePathForMatch(item.path)) ? ' is-active' : ''
+                          }`}
+                        >
                           {item.menu.map((subItem) => (
                             <li key={subItem.path}>
                               <Link
-                                href={`/${subItem.path}`}
+                                href={toAbsolutePath(subItem.path)}
                                 className="text-[1rem] opacity-80"
                                 onClick={() => {
-                                  router.push(`/${subItem.path}`);
                                   setOpen(false);
                                 }}
                               >

package/src/app/components/util/index.ts

@@ -290,10 +290,10 @@ export const staticBuildMenu = () => {
 };
 
 const buildBasePath = () => {
-  if(!process.env.HANDOFF_APP_BASE_PATH) {
+  if (!process.env.HANDOFF_APP_BASE_PATH) {
     return '';
   }
-  return (process.env.HANDOFF_APP_BASE_PATH ?? '').replace(/^\//, '') + '/';
+  return (process.env.HANDOFF_APP_BASE_PATH ?? '').replace(/^\/+|\/+$/g, '') + '/';
 };
 
 const staticBuildComponentMenu = (type?: boolean | string) => {

package/src/app/lib/utils.ts

@@ -5,6 +5,19 @@ export function cn(...inputs: ClassValue[]) {
   return twMerge(clsx(inputs));
 }
 
+export const trimSlashes = (input: string): string => {
+  return input.replace(/^\/+|\/+$/g, '');
+};
+
+export const toAbsolutePath = (input: string): string => {
+  return `/${trimSlashes(input)}`;
+};
+
+export const normalizePathForMatch = (input: string): string => {
+  const [pathname] = input.split(/[?#]/);
+  return trimSlashes(pathname);
+};
+
 /**
  * Filters out null values
  * @param value

package/src/app/next.config.mjs

@@ -2,6 +2,14 @@ import chalk from 'chalk';
 import fs from 'fs-extra';
 import path from 'path';
 
+const resolveBasePath = (rawBasePath) => {
+  if (!rawBasePath || rawBasePath.startsWith('%HANDOFF_')) {
+    return '';
+  }
+  const trimmed = rawBasePath.replace(/^\/+|\/+$/g, '');
+  return trimmed ? `/${trimmed}` : '';
+};
+
 /** @type {import('next').NextConfig} */
 const nextConfig = {
   output: 'export',
@@ -19,14 +27,14 @@ const nextConfig = {
     tsconfigPath: 'tsconfig.json',
   },
   //distDir: 'out',
-  basePath: '',
+  basePath: resolveBasePath('%HANDOFF_APP_BASE_PATH%'),
   env: {
-    HANDOFF_PROJECT_ID: '',
-    HANDOFF_APP_BASE_PATH: '',
-    HANDOFF_WORKING_PATH: '',
-    HANDOFF_MODULE_PATH: '',
-    HANDOFF_EXPORT_PATH: '',
-    HANDOFF_WEBSOCKET_PORT: '',
+    HANDOFF_PROJECT_ID: '%HANDOFF_PROJECT_ID%',
+    HANDOFF_APP_BASE_PATH: '%HANDOFF_APP_BASE_PATH%',
+    HANDOFF_WORKING_PATH: '%HANDOFF_WORKING_PATH%',
+    HANDOFF_MODULE_PATH: '%HANDOFF_MODULE_PATH%',
+    HANDOFF_EXPORT_PATH: '%HANDOFF_EXPORT_PATH%',
+    HANDOFF_WEBSOCKET_PORT: '%HANDOFF_WEBSOCKET_PORT%',
   },
   images: {
     unoptimized: true,
@@ -38,12 +46,12 @@ const nextConfig = {
 
       // Local environment
       const env = {
-        HANDOFF_PROJECT_ID: '',
-        HANDOFF_APP_BASE_PATH: '',
-        HANDOFF_WORKING_PATH: '',
-        HANDOFF_MODULE_PATH: '',
-        HANDOFF_EXPORT_PATH: '',
-        HANDOFF_WEBSOCKET_PORT: '',
+        HANDOFF_PROJECT_ID: '%HANDOFF_PROJECT_ID%',
+        HANDOFF_APP_BASE_PATH: '%HANDOFF_APP_BASE_PATH%',
+        HANDOFF_WORKING_PATH: '%HANDOFF_WORKING_PATH%',
+        HANDOFF_MODULE_PATH: '%HANDOFF_MODULE_PATH%',
+        HANDOFF_EXPORT_PATH: '%HANDOFF_EXPORT_PATH%',
+        HANDOFF_WEBSOCKET_PORT: '%HANDOFF_WEBSOCKET_PORT%',
       };
 
       // Check if client configuration exists

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

@@ -163,7 +163,7 @@ const GenericComponentPage = ({ menu, metadata, current, id, config, componentHo
   }, [component, id]);
 
   if (!component) return <p>Loading...</p>;
-  const apiUrl = (window.location.origin && window.location.origin) + `/api/component/${id}.json`;
+  const apiUrl = (window.location.origin && window.location.origin) + `${normalizedBasePath}/api/component/${id}.json`;
   return (
     <Layout config={config} menu={menu} current={current} metadata={metadata}>
       <div className="flex flex-col gap-3 pb-14">

package/src/app-builder/build.ts

@@ -12,6 +12,8 @@ import { getAppPath, syncPublicFiles } from './paths';
 import { WatcherState, getRuntimeComponentsPathsToWatch, watchAppSource, watchGlobalEntries, watchPages, watchPublicDirectory, watchRuntimeComponents, watchRuntimeConfiguration } from './watchers';
 import { createWebSocketServer } from './websocket';
 
+const escapeForSingleQuotedJsString = (value: string): string => value.replace(/\\/g, '\\\\').replace(/'/g, "\\'");
+
 /**
  * Performs cleanup of the application directory by removing the existing app directory if it exists.
  */
@@ -49,8 +51,7 @@ const initializeProjectApp = async (handoff: Handoff): Promise<string> => {
     Logger.success(`Custom theme.css loaded`);
   }
 
-  // Prepare project app configuration
-  // Warning: Regex replacement is fragile and depends on exact formatting in next.config.mjs
+  // Prepare project app configuration using stable placeholder replacement.
   const handoffProjectId = handoff.getProjectId();
   const handoffAppBasePath = handoff.config.app.base_path ?? '';
   const handoffWorkingPath = path.resolve(handoff.workingPath);
@@ -59,15 +60,24 @@ const initializeProjectApp = async (handoff: Handoff): Promise<string> => {
   const nextConfigPath = path.resolve(srcPath, 'next.config.mjs');
   const targetPath = path.resolve(appPath, 'next.config.mjs');
   const handoffWebsocketPort = handoff.config.app.ports?.websocket ?? 3001;
-  const nextConfigContent = (await fs.readFile(nextConfigPath, 'utf-8'))
-    .replace(/basePath:\s+''/g, `basePath: '${handoffAppBasePath}'`)
-    .replace(/HANDOFF_PROJECT_ID:\s+''/g, `HANDOFF_PROJECT_ID: '${handoffProjectId}'`)
-    .replace(/HANDOFF_APP_BASE_PATH:\s+''/g, `HANDOFF_APP_BASE_PATH: '${handoffAppBasePath}'`)
-    .replace(/HANDOFF_WORKING_PATH:\s+''/g, `HANDOFF_WORKING_PATH: '${handoffWorkingPath}'`)
-    .replace(/HANDOFF_MODULE_PATH:\s+''/g, `HANDOFF_MODULE_PATH: '${handoffModulePath}'`)
-    .replace(/HANDOFF_EXPORT_PATH:\s+''/g, `HANDOFF_EXPORT_PATH: '${handoffExportPath}'`)
-    .replace(/HANDOFF_WEBSOCKET_PORT:\s+''/g, `HANDOFF_WEBSOCKET_PORT: '${handoffWebsocketPort}'`)
-    .replace(/%HANDOFF_MODULE_PATH%/g, handoffModulePath);
+  const escapedAppBasePath = escapeForSingleQuotedJsString(handoffAppBasePath);
+  const escapedProjectId = escapeForSingleQuotedJsString(handoffProjectId);
+  const escapedWorkingPath = escapeForSingleQuotedJsString(handoffWorkingPath);
+  const escapedModulePath = escapeForSingleQuotedJsString(handoffModulePath);
+  const escapedExportPath = escapeForSingleQuotedJsString(handoffExportPath);
+  const escapedWebsocketPort = escapeForSingleQuotedJsString(String(handoffWebsocketPort));
+  const placeholderValues: Record<string, string> = {
+    '%HANDOFF_PROJECT_ID%': escapedProjectId,
+    '%HANDOFF_APP_BASE_PATH%': escapedAppBasePath,
+    '%HANDOFF_WORKING_PATH%': escapedWorkingPath,
+    '%HANDOFF_MODULE_PATH%': escapedModulePath,
+    '%HANDOFF_EXPORT_PATH%': escapedExportPath,
+    '%HANDOFF_WEBSOCKET_PORT%': escapedWebsocketPort,
+  };
+  let nextConfigContent = await fs.readFile(nextConfigPath, 'utf-8');
+  for (const [placeholder, value] of Object.entries(placeholderValues)) {
+    nextConfigContent = nextConfigContent.split(placeholder).join(value);
+  }
   await fs.writeFile(targetPath, nextConfigContent);
   return appPath;
 };

package/src/app-builder/watchers.ts

@@ -7,6 +7,7 @@ import { buildMainJS } from '../transformers/preview/component/javascript';
 import processComponents, { ComponentSegment } from '../transformers/preview/component/builder';
 import { ComponentListObject } from '../transformers/preview/types';
 import { Logger } from '../utils/logger';
+import { isPathInside, normalizePathForCompare } from '../utils/path';
 import { persistClientConfig } from './client-config';
 import { syncPublicFiles } from './paths';
 
@@ -115,12 +116,6 @@ export const watchGlobalEntries = (handoff: Handoff, state: WatcherState, chokid
   const pathsToWatch = [...scssPathsToWatch, ...jsPathsToWatch];
   if (pathsToWatch.length === 0) return;
 
-  const isPathInside = (filePath: string, parentPath: string): boolean => {
-    const normalizedFilePath = path.resolve(filePath);
-    const normalizedParentPath = path.resolve(parentPath);
-    return normalizedFilePath === normalizedParentPath || normalizedFilePath.startsWith(`${normalizedParentPath}${path.sep}`);
-  };
-
   chokidar.watch(pathsToWatch, chokidarConfig).on('all', async (event, file) => {
     switch (event) {
       case 'add':
@@ -206,11 +201,17 @@ export const watchRuntimeComponents = (
 
   if (runtimeComponentPathsToWatch.size > 0) {
     const pathsToWatch = Array.from(runtimeComponentPathsToWatch.keys());
+    const runtimeComponentEntryTypeByPath = new Map<string, keyof ComponentListObject['entries']>(
+      Array.from(runtimeComponentPathsToWatch.entries()).map(([watchPath, entryType]) => [normalizePathForCompare(watchPath), entryType])
+    );
+    const configFileSet = new Set(handoff.getConfigFilePaths().map((configPath) => normalizePathForCompare(configPath)));
+
     state.runtimeComponentsWatcher = chokidar.watch(pathsToWatch, {
       ignoreInitial: true,
     });
     state.runtimeComponentsWatcher.on('all', async (event, file) => {
-      if (handoff.getConfigFilePaths().includes(file)) {
+      const normalizedFile = normalizePathForCompare(file);
+      if (configFileSet.has(normalizedFile)) {
         return;
       }
 
@@ -221,7 +222,7 @@ export const watchRuntimeComponents = (
           if (!state.debounce) {
             state.debounce = true;
             try {
-              const entryType = runtimeComponentPathsToWatch.get(file);
+              const entryType = runtimeComponentEntryTypeByPath.get(normalizedFile);
               const segmentToUpdate: ComponentSegment = entryType ? mapEntryTypeToSegment(entryType) : undefined;
 
               const componentDir = path.basename(path.dirname(file));

package/src/cache/build-cache.ts

@@ -2,6 +2,7 @@ import fs from 'fs-extra';
 import path from 'path';
 import Handoff from '../index';
 import { Logger } from '../utils/logger';
+import { normalizePathForCompare } from '../utils/path';
 import { computeDirectoryState, computeFileState, directoryStatesMatch, FileState, statesMatch } from './file-state';
 
 /** Current cache format version - bump when structure changes */
@@ -162,25 +163,18 @@ export function getComponentFilePaths(handoff: Handoff, componentId: string): {
 
   const files: string[] = [];
   let templateDir: string | undefined;
+  const componentDirs = new Set<string>();
 
-  // Find the config file path for this component
-  const configPaths = handoff.getConfigFilePaths();
-  for (const configPath of configPaths) {
-    // Check if this config path belongs to this component
-    if (configPath.includes(componentId)) {
-      files.push(configPath);
-      break;
-    }
-  }
-
-  // Add entry files
+  // Add entry files and infer component directories from resolved entry paths
   const entries = runtimeComponent.entries as Record<string, string | undefined> | undefined;
   if (entries) {
     if (entries.js) {
       files.push(entries.js);
+      componentDirs.add(normalizePathForCompare(path.dirname(entries.js)));
     }
     if (entries.scss) {
       files.push(entries.scss);
+      componentDirs.add(normalizePathForCompare(path.dirname(entries.scss)));
     }
     // Handle both 'template' (singular) and 'templates' (plural) entry types
     const templatePath = entries.template || entries.templates;
@@ -189,16 +183,40 @@ export function getComponentFilePaths(handoff: Handoff, componentId: string): {
         const stat = fs.statSync(templatePath);
         if (stat.isDirectory()) {
           templateDir = templatePath;
+          componentDirs.add(normalizePathForCompare(templatePath));
         } else {
           files.push(templatePath);
+          componentDirs.add(normalizePathForCompare(path.dirname(templatePath)));
         }
       } catch {
         // File doesn't exist, still add to track
         files.push(templatePath);
+        componentDirs.add(normalizePathForCompare(path.dirname(templatePath)));
       }
     }
   }
 
+  // Find the config file path for this component using exact config filename + directory matching.
+  const configPaths = handoff.getConfigFilePaths();
+  const expectedConfigFileNames = new Set([`${componentId}.json`, `${componentId}.js`, `${componentId}.cjs`]);
+  const matchingConfigPath = configPaths.find((configPath) => {
+    const configFileName = path.basename(configPath);
+    if (!expectedConfigFileNames.has(configFileName)) {
+      return false;
+    }
+
+    if (componentDirs.size === 0) {
+      return true;
+    }
+
+    const configDir = normalizePathForCompare(path.dirname(configPath));
+    return componentDirs.has(configDir);
+  });
+
+  if (matchingConfigPath) {
+    files.push(matchingConfigPath);
+  }
+
   return { files, templateDir };
 }
 

package/src/cli.ts

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

package/src/transformers/plugins/handlebars-previews.ts

@@ -158,6 +158,17 @@ export function handlebarsPreviewsPlugin(
       // Process component instances from documentation
       processComponentInstances(componentData, documentationComponents);
 
+      if (!componentData.previews || Object.keys(componentData.previews).length === 0) {
+        Logger.warn(`No previews defined for ${componentId}; using default preview values.`);
+        componentData.previews = {
+          default: {
+            title: 'Default',
+            values: {},
+            url: '',
+          },
+        };
+      }
+
       const generatedPreviews: { [key: string]: string } = {};
 
       // Generate previews for each variation
@@ -202,7 +213,8 @@ export function handlebarsPreviewsPlugin(
       componentData.format = PLUGIN_CONSTANTS.OUTPUT_FORMAT;
       componentData.preview = '';
       componentData.code = trimPreview(templateContent);
-      componentData.html = trimPreview(generatedPreviews[Object.keys(generatedPreviews)[0]]);
+      const firstGeneratedPreview = Object.values(generatedPreviews)[0];
+      componentData.html = trimPreview(firstGeneratedPreview ?? templateContent);
     },
   };
 }

package/src/transformers/preview/component/builder.ts

@@ -62,6 +62,19 @@ type ComponentBuildPlan = {
   validationMode: boolean;
 };
 
+const ensureDefaultPreview = (data: TransformComponentTokensResult): void => {
+  if (!data) return;
+  if (!data.previews || Object.keys(data.previews).length === 0) {
+    data.previews = {
+      default: {
+        title: 'Default',
+        values: {},
+        url: '',
+      },
+    };
+  }
+};
+
 /**
  * Returns a normalized build plan describing which component segments need rebuilding.
  *
@@ -223,7 +236,7 @@ export async function processComponents(
     // those will override this default (standard "config overrides defaults" behavior).
     if (!restMetadata.figmaComponentId) {
       componentDefaults.previews = {
-        generic: {
+        default: {
           title: 'Default',
           values: {},
           url: '',
@@ -276,6 +289,9 @@ export async function processComponents(
       }
     }
 
+    // Components should always have at least one preview variation.
+    ensureDefaultPreview(data);
+
     // Build JS if needed (new build, validation missing, or explicit segment request).
     if (buildPlan.js) {
       data = await buildComponentJs(data, handoff);

package/src/transformers/utils/html.ts

@@ -7,9 +7,22 @@ import prettier from 'prettier';
  * @returns Trimmed HTML content
  */
 export const trimPreview = (preview: string): string => {
-  const bodyEl = parse(preview).querySelector('body');
-  const code = bodyEl ? bodyEl.innerHTML.trim() : preview;
-  return code;
+  if (typeof preview !== 'string') {
+    return '';
+  }
+
+  const normalizedPreview = preview.trim();
+  if (!normalizedPreview) {
+    return '';
+  }
+
+  try {
+    const bodyEl = parse(normalizedPreview).querySelector('body');
+    return bodyEl ? bodyEl.innerHTML.trim() : normalizedPreview;
+  } catch {
+    // Keep build resilient if parser fails on malformed HTML.
+    return normalizedPreview;
+  }
 };
 
 /**

package/src/utils/path.ts

@@ -1,3 +1,5 @@
+import path from 'path';
+
 /**
  * Generates a filesystem-safe directory name from an absolute path
  * @param workingPath - The absolute working path to transform
@@ -30,3 +32,30 @@ export function generateFilesystemSafeId(workingPath: string): string {
   return safeId;
 }
 
+/**
+ * Normalize a filesystem path for cross-platform string comparison.
+ * - Resolves to absolute path
+ * - Normalizes separators to forward slashes
+ * - Lowercases on Windows where paths are case-insensitive
+ */
+export function normalizePathForCompare(inputPath: string): string {
+  const normalized = path.resolve(inputPath).replace(/\\/g, '/');
+  return process.platform === 'win32' ? normalized.toLowerCase() : normalized;
+}
+
+/**
+ * True when both paths resolve to the same normalized filesystem path.
+ */
+export function arePathsEqual(pathA: string, pathB: string): boolean {
+  return normalizePathForCompare(pathA) === normalizePathForCompare(pathB);
+}
+
+/**
+ * True when childPath is equal to or within parentPath.
+ */
+export function isPathInside(childPath: string, parentPath: string): boolean {
+  const normalizedChild = normalizePathForCompare(childPath);
+  const normalizedParent = normalizePathForCompare(parentPath);
+  return normalizedChild === normalizedParent || normalizedChild.startsWith(`${normalizedParent}/`);
+}
+

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