handoff-app 1.1.0 → 1.1.2-0

package/Changelog.md

@@ -6,6 +6,61 @@ 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.2] - 2026-03-26
+
+This release improves integration with downstream platforms (for example HubSpot) by letting
+projects register their own Handlebars helpers during preview generation, instead of relying
+only on Handoff’s built-in `field` and `eq` helpers.
+
+### Feature
+
+**`hooks.registerHandlebarsHelpers`** — New optional hook in `handoff.config.js`. After Handoff
+registers its default preview helpers, your callback runs with the Handlebars runtime, the
+current `componentId`, the component `properties` (slot metadata), and a flag for inspect-mode
+renders (`injectFieldWrappers`). Use `handlebars.registerHelper` (and block helpers as needed)
+to add helpers that are only available while building component preview HTML—so templates can
+stay platform-specific without forking Handoff.
+
+Typical uses: block helpers that wrap regions meant for a host page’s header or footer, or a
+helper that serializes a value as JSON for inline scripts. Those behaviors are **not** shipped
+as core helpers; you define them in config so each project controls naming and semantics.
+
+See `docs/api.md` (Hooks → `registerHandlebarsHelpers`) for the full signature and README
+“Configuration hooks” for a quick pointer.
+
+### Example: JSON in templates
+
+If you register a `json` helper in `hooks.registerHandlebarsHelpers`, like this
+
+```
+  hooks: {
+    registerHandlebarsHelpers: ({ handlebars, componentId }) => {
+      // Register 'json' as a simple (non-block) helper
+      handlebars.registerHelper('json', (value, data) => {
+        return new handlebars.SafeString(JSON.stringify(value, null, 2));
+      });
+    }
+  }
+```
+
+Then your templates can do:
+
+```
+<script type="text/javascript">
+  window.barChartData = {{{json properties.data}}};
+</script>
+```
+
+with output shaped by your helper implementation (for example serialized JSON for chart data).
+
+## \[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
@@ -1822,3 +1877,6 @@ package version was set to ^0.1.0 rather than ^0.2.0. This release fixes that.
 
 ```
 ```
+
+```
+```

package/README.md

@@ -16,6 +16,7 @@ transform tokens into dev ready artifacts.
 * [How does it work](#how-does-it-work)
   * [Handoff is in Beta!](#handoff-is-in-beta)
 * [Requirements](#requirements)
+* [Configuration hooks](#configuration-hooks)
 * [Get Started](#get-started)
   * [Figma](#figma)
   * [Create a project](#create-a-project)
@@ -168,6 +169,12 @@ handoff-app start
 
 Once that runs, your browser should update with the new colors.
 
+## Configuration hooks
+
+Pipeline customization is done in `handoff.config.js` under `hooks` (camelCase names: `validateComponent`, `jsBuildConfig`, `registerHandlebarsHelpers`, etc.). For example, `registerHandlebarsHelpers` runs after Handoff registers the built-in `field` and `eq` helpers so you can call `handlebars.registerHelper` for your `.hbs` preview templates.
+
+See [docs/api.md](docs/api.md#hooks) for hook arguments and examples.
+
 ## Further Reading
 
 * [Configure your project](https://www.handoff.com/docs/customization)

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.2';
 };
 /**
  * Define a CLI error

package/dist/index.d.ts

@@ -95,6 +95,6 @@ declare class Handoff {
     private readJsonFile;
 }
 export type { ComponentObject as Component } from './transformers/preview/types';
-export type { Config } from './types/config';
+export type { Config, RegisterHandlebarsHelpersContext } from './types/config';
 export { Transformers as CoreTransformers, TransformerUtils as CoreTransformerUtils, Types as CoreTypes } from 'handoff-core';
 export default Handoff;

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

@@ -61,10 +61,11 @@ function processComponentInstances(componentData, documentationComponents) {
  * @param injectFieldWrappers - Whether to inject field wrappers for inspection
  * @returns Rendered HTML string
  */
-function renderHandlebarsTemplate(template, componentData, previewData, injectFieldWrappers) {
+function renderHandlebarsTemplate(template, componentData, previewData, injectFieldWrappers, handoff) {
     return __awaiter(this, void 0, void 0, function* () {
+        var _a, _b;
         // Register Handlebars helpers with current injection state
-        (0, handlebars_2.registerHandlebarsHelpers)({ id: componentData.id, properties: componentData.properties || {} }, injectFieldWrappers);
+        (0, handlebars_2.registerHandlebarsHelpers)({ id: componentData.id, properties: componentData.properties || {} }, injectFieldWrappers, (_b = (_a = handoff.config) === null || _a === void 0 ? void 0 : _a.hooks) === null || _b === void 0 ? void 0 : _b.registerHandlebarsHelpers);
         const context = (0, handlebars_2.createHandlebarsContext)({
             id: componentData.id,
             properties: componentData.properties || {},
@@ -131,14 +132,24 @@ 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) {
                     try {
                         const previewData = componentData.previews[previewKey];
                         // Render both normal and inspect modes
-                        const normalModeHtml = yield renderHandlebarsTemplate(templateContent, componentData, previewData, false);
-                        const inspectModeHtml = yield renderHandlebarsTemplate(templateContent, componentData, previewData, true);
+                        const normalModeHtml = yield renderHandlebarsTemplate(templateContent, componentData, previewData, false, handoff);
+                        const inspectModeHtml = yield renderHandlebarsTemplate(templateContent, componentData, previewData, true, handoff);
                         // Emit preview files
                         emitPreviewFiles(componentId, previewKey, normalModeHtml, inspectModeHtml, (file) => this.emitFile(file));
                         generatedPreviews[previewKey] = normalModeHtml;
@@ -153,7 +164,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/handlebars.d.ts

@@ -1,16 +1,18 @@
+import { RegisterHandlebarsHelpersContext } from '../../types/config';
 import { SlotMetadata } from '../preview/component';
 import { HandlebarsContext } from '../types';
 /**
- * Registers common Handlebars helpers
+ * Registers common Handlebars helpers, then runs optional `hooks.registerHandlebarsHelpers`.
  * @param data - Component data containing properties
  * @param injectFieldWrappers - Whether to inject field wrappers for inspection
+ * @param extend - Optional callback from config to register additional helpers
  */
 export declare const registerHandlebarsHelpers: (data: {
     properties: {
         [key: string]: SlotMetadata;
     };
     id: string;
-}, injectFieldWrappers: boolean) => void;
+}, injectFieldWrappers: boolean, extend?: (context: RegisterHandlebarsHelpersContext) => void) => void;
 /**
  * Creates Handlebars template context
  * @param data - Component data

package/dist/transformers/utils/handlebars.js

@@ -7,11 +7,12 @@ exports.createHandlebarsContext = exports.registerHandlebarsHelpers = void 0;
 const handlebars_1 = __importDefault(require("handlebars"));
 const logger_1 = require("../../utils/logger");
 /**
- * Registers common Handlebars helpers
+ * Registers common Handlebars helpers, then runs optional `hooks.registerHandlebarsHelpers`.
  * @param data - Component data containing properties
  * @param injectFieldWrappers - Whether to inject field wrappers for inspection
+ * @param extend - Optional callback from config to register additional helpers
  */
-const registerHandlebarsHelpers = (data, injectFieldWrappers) => {
+const registerHandlebarsHelpers = (data, injectFieldWrappers, extend) => {
     // Field helper for property binding
     handlebars_1.default.registerHelper('field', function (field, options) {
         if (injectFieldWrappers) {
@@ -43,6 +44,12 @@ const registerHandlebarsHelpers = (data, injectFieldWrappers) => {
     handlebars_1.default.registerHelper('eq', function (a, b) {
         return a === b;
     });
+    extend === null || extend === void 0 ? void 0 : extend({
+        handlebars: handlebars_1.default,
+        componentId: data.id,
+        properties: data.properties,
+        injectFieldWrappers,
+    });
 };
 exports.registerHandlebarsHelpers = registerHandlebarsHelpers;
 /**
@@ -54,9 +61,7 @@ exports.registerHandlebarsHelpers = registerHandlebarsHelpers;
 const createHandlebarsContext = (data, previewData, options) => {
     var _a;
     const basePath = (_a = process.env.HANDOFF_APP_BASE_PATH) !== null && _a !== void 0 ? _a : '';
-    const sharedStylesLink = (options === null || options === void 0 ? void 0 : options.includeSharedStyles)
-        ? `<link rel="stylesheet" href="${basePath}/api/component/shared.css">`
-        : '';
+    const sharedStylesLink = (options === null || options === void 0 ? void 0 : options.includeSharedStyles) ? `<link rel="stylesheet" href="${basePath}/api/component/shared.css">` : '';
     return {
         style: `${sharedStylesLink}<link rel="stylesheet" href="${basePath}/api/component/main.css">` +
             `<link rel="stylesheet" href="${basePath}/api/component/${data.id}.css">\n` +

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/types/config.d.ts

@@ -1,4 +1,5 @@
 import { BuildOptions } from 'esbuild';
+import type Handlebars from 'handlebars';
 import { Types as HandoffTypes } from 'handoff-core';
 import { InlineConfig } from 'vite';
 import { SlotMetadata } from '../transformers/preview/component';
@@ -51,6 +52,15 @@ export interface Breakpoints {
         name: string;
     };
 }
+/** Context passed to the `registerHandlebarsHelpers` config hook after built-in helpers (`field`, `eq`) are registered for a preview render. */
+export type RegisterHandlebarsHelpersContext = {
+    handlebars: typeof Handlebars;
+    componentId: string;
+    properties: {
+        [key: string]: SlotMetadata;
+    };
+    injectFieldWrappers: boolean;
+};
 export interface NextAppConfig {
     theme?: string;
     title: string;
@@ -238,6 +248,21 @@ export interface Config {
          * ```
          */
         htmlBuildConfig?: (config: InlineConfig) => InlineConfig;
+        /**
+         * Optional hook invoked after Handoff registers built-in Handlebars helpers for
+         * component preview HTML. Use `context.handlebars.registerHelper` to add or
+         * replace helpers. Called once per preview render (per variation and inspect mode).
+         *
+         * @param context - Handlebars runtime, component id/properties, and whether
+         *   inspect field wrappers are enabled for this render.
+         * @example
+         * ```typescript
+         * registerHandlebarsHelpers: ({ handlebars, componentId }) => {
+         *   handlebars.registerHelper('upperId', () => componentId.toUpperCase());
+         * }
+         * ```
+         */
+        registerHandlebarsHelpers?: (context: RegisterHandlebarsHelpersContext) => void;
     };
 }
 export type ClientConfig = Pick<Config, 'app' | 'exportsOutputDirectory' | 'sitesOutputDirectory' | 'assets_zip_links' | 'useVariables'>;

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}/`);
+}