handoff-app 1.1.0-experimental.2 → 1.1.1

package/dist/config/runtime.js

@@ -3,7 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.toLowerCaseKeysAndValues = exports.getPagesForPath = exports.getComponentsForPath = exports.initRuntimeConfig = void 0;
+exports.toLowerCaseKeysAndValues = exports.getComponentsForPath = exports.initRuntimeConfig = void 0;
 const fs_extra_1 = __importDefault(require("fs-extra"));
 const path_1 = __importDefault(require("path"));
 const logger_1 = require("../utils/logger");
@@ -15,8 +15,8 @@ const logger_1 = require("../utils/logger");
  * @returns A tuple of [RuntimeConfig, configFilePaths].
  */
 const initRuntimeConfig = (handoff) => {
-    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k;
-    var _l;
+    var _a, _b, _c, _d, _e, _f, _g, _h;
+    var _j;
     const configFiles = [];
     const result = {
         options: {},
@@ -24,7 +24,6 @@ const initRuntimeConfig = (handoff) => {
             scss: undefined,
             js: undefined,
             components: {},
-            pages: {},
         },
     };
     if (!!((_a = handoff.config.entries) === null || _a === void 0 ? void 0 : _a.scss)) {
@@ -77,7 +76,7 @@ const initRuntimeConfig = (handoff) => {
             component.options || (component.options = {
                 transformer: { defaults: {}, replace: {} },
             });
-            (_l = component.options).transformer || (_l.transformer = { defaults: {}, replace: {} });
+            (_j = component.options).transformer || (_j.transformer = { defaults: {}, replace: {} });
             const transformer = component.options.transformer;
             (_g = transformer.cssRootClass) !== null && _g !== void 0 ? _g : (transformer.cssRootClass = null);
             (_h = transformer.tokenNameSegments) !== null && _h !== void 0 ? _h : (transformer.tokenNameSegments = null);
@@ -90,47 +89,6 @@ const initRuntimeConfig = (handoff) => {
             result.entries.components[component.id] = component;
         }
     }
-    if ((_k = (_j = handoff.config.entries) === null || _j === void 0 ? void 0 : _j.pages) === null || _k === void 0 ? void 0 : _k.length) {
-        const pagePaths = handoff.config.entries.pages.flatMap(exports.getPagesForPath);
-        for (const pagePath of pagePaths) {
-            const resolvedPagePath = path_1.default.resolve(handoff.workingPath, pagePath);
-            const pageBaseName = path_1.default.basename(resolvedPagePath);
-            const possibleConfigFiles = [`${pageBaseName}.json`, `${pageBaseName}.js`, `${pageBaseName}.cjs`];
-            const configFileName = possibleConfigFiles.find((file) => fs_extra_1.default.existsSync(path_1.default.resolve(resolvedPagePath, file)));
-            if (!configFileName) {
-                logger_1.Logger.warn(`Missing page config: ${path_1.default.resolve(resolvedPagePath, possibleConfigFiles.join(' or '))}`);
-                continue;
-            }
-            const resolvedPageConfigPath = path_1.default.resolve(resolvedPagePath, configFileName);
-            configFiles.push(resolvedPageConfigPath);
-            let page;
-            try {
-                if (configFileName.endsWith('.json')) {
-                    const pageJson = fs_extra_1.default.readFileSync(resolvedPageConfigPath, 'utf8');
-                    page = JSON.parse(pageJson);
-                }
-                else {
-                    delete require.cache[require.resolve(resolvedPageConfigPath)];
-                    const importedPage = require(resolvedPageConfigPath);
-                    page = importedPage.default || importedPage;
-                }
-            }
-            catch (err) {
-                logger_1.Logger.error(`Failed to read or parse page config: ${resolvedPageConfigPath}`, err);
-                continue;
-            }
-            page.id = pageBaseName;
-            // Validate that referenced components exist
-            if (page.components) {
-                for (const componentId of page.components) {
-                    if (!result.entries.components[componentId]) {
-                        logger_1.Logger.warn(`Page '${page.id}' references unknown component '${componentId}'`);
-                    }
-                }
-            }
-            result.entries.pages[page.id] = page;
-        }
-    }
     return [result, Array.from(configFiles)];
 };
 exports.initRuntimeConfig = initRuntimeConfig;
@@ -170,27 +128,6 @@ const getComponentsForPath = (searchPath) => {
     return [searchPath];
 };
 exports.getComponentsForPath = getComponentsForPath;
-/**
- * Returns a list of page directories for a given path.
- * Mirrors getComponentsForPath but for page definitions.
- */
-const getPagesForPath = (searchPath) => {
-    const dirName = path_1.default.basename(searchPath);
-    const possibleConfigFiles = [`${dirName}.json`, `${dirName}.js`, `${dirName}.cjs`];
-    const hasOwnConfig = possibleConfigFiles.some((file) => fs_extra_1.default.existsSync(path_1.default.resolve(searchPath, file)));
-    if (hasOwnConfig) {
-        return [searchPath];
-    }
-    const subdirectories = fs_extra_1.default
-        .readdirSync(searchPath, { withFileTypes: true })
-        .filter((entry) => entry.isDirectory())
-        .map((entry) => entry.name);
-    if (subdirectories.length > 0) {
-        return subdirectories.map((subdir) => path_1.default.join(searchPath, subdir));
-    }
-    return [searchPath];
-};
-exports.getPagesForPath = getPagesForPath;
 /**
  * Recursively converts all keys and string values in an object to lowercase.
  */

package/dist/index.d.ts

@@ -26,10 +26,7 @@ declare class Handoff {
     preRunner(validate?: boolean): Handoff;
     fetch(): Promise<Handoff>;
     component(name: string | null): Promise<Handoff>;
-    build(skipComponents?: boolean, options?: {
-        copyOnlyPaths?: string[];
-        deployDir?: string;
-    }): Promise<Handoff>;
+    build(skipComponents?: boolean): Promise<Handoff>;
     ejectConfig(): Promise<Handoff>;
     ejectPages(): Promise<Handoff>;
     ejectTheme(): Promise<Handoff>;

package/dist/index.js

@@ -114,10 +114,10 @@ class Handoff {
             return this;
         });
     }
-    build(skipComponents, options) {
+    build(skipComponents) {
         return __awaiter(this, void 0, void 0, function* () {
             this.preRunner();
-            yield (0, app_builder_1.default)(this, skipComponents, options);
+            yield (0, app_builder_1.default)(this, skipComponents);
             return this;
         });
     }

package/dist/pipeline/index.d.ts

@@ -2,7 +2,6 @@ import 'dotenv/config';
 import Handoff from '..';
 export { readPrevJSONFile, zip, zipAssets } from './archive';
 export { buildComponents } from './components';
-export { buildPages } from './pages';
 /**
  * Run the entire Figma data pipeline:
  * 1. Validate runtime requirements

package/dist/pipeline/index.js

@@ -12,7 +12,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.buildPages = exports.buildComponents = exports.zipAssets = exports.zip = exports.readPrevJSONFile = void 0;
+exports.buildComponents = exports.zipAssets = exports.zip = exports.readPrevJSONFile = void 0;
 require("dotenv/config");
 const app_builder_1 = __importDefault(require("../app-builder"));
 const logger_1 = require("../utils/logger");
@@ -26,8 +26,6 @@ Object.defineProperty(exports, "zip", { enumerable: true, get: function () { ret
 Object.defineProperty(exports, "zipAssets", { enumerable: true, get: function () { return archive_1.zipAssets; } });
 var components_1 = require("./components");
 Object.defineProperty(exports, "buildComponents", { enumerable: true, get: function () { return components_1.buildComponents; } });
-var pages_1 = require("./pages");
-Object.defineProperty(exports, "buildPages", { enumerable: true, get: function () { return pages_1.buildPages; } });
 /**
  * Run the entire Figma data pipeline:
  * 1. Validate runtime requirements

package/dist/transformers/plugins/csf-render.js

@@ -20,7 +20,6 @@ const react_1 = __importDefault(require("react"));
 const server_1 = __importDefault(require("react-dom/server"));
 const logger_1 = require("../../utils/logger");
 const component_1 = require("../preview/component");
-const build_1 = require("../utils/build");
 const html_1 = require("../utils/html");
 const module_1 = require("../utils/module");
 const schema_1 = require("../utils/schema");
@@ -154,7 +153,7 @@ function csfRenderPlugin(componentData, _documentationComponents, handoff) {
         },
         generateBundle(_, bundle) {
             return __awaiter(this, void 0, void 0, function* () {
-                var _a, _b, _c, _d, _e, _f;
+                var _a, _b, _c, _d, _e;
                 for (const [fileName, chunkInfo] of Object.entries(bundle)) {
                     if (chunkInfo.type === 'chunk' && fileName.includes(PLUGIN_CONSTANTS.SCRIPT_ID)) {
                         delete bundle[fileName];
@@ -261,22 +260,6 @@ function csfRenderPlugin(componentData, _documentationComponents, handoff) {
                     preview.url = fileName;
                     lastHtml = html;
                 }
-                // Emit standalone client module for Playground live rendering
-                const firstStoryKey = (_f = stories[0]) === null || _f === void 0 ? void 0 : _f[0];
-                if (firstStoryKey) {
-                    try {
-                        const clientModuleSource = (0, build_1.generateCsfClientComponentSource)(templatePath, firstStoryKey);
-                        const clientModuleJs = yield (0, build_1.buildClientModule)(clientModuleSource, handoff);
-                        this.emitFile({
-                            type: 'asset',
-                            fileName: `${componentId}.module.js`,
-                            source: clientModuleJs,
-                        });
-                    }
-                    catch (error) {
-                        logger_1.Logger.warn(`Failed to build client module for ${componentId}: ${error}`);
-                    }
-                }
                 componentData.format = 'react';
                 componentData.preview = '';
                 componentData.code = (0, html_1.trimPreview)(sourceCode);

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/plugins/ssr-render.js

@@ -257,20 +257,6 @@ function ssrRenderPlugin(componentData, documentationComponents, handoff) {
                     generatedPreviews[previewKey] = finalHtml;
                     componentData.previews[previewKey].url = `${componentId}-${previewKey}.html`;
                 }
-                // Emit standalone client module for Playground live rendering
-                console.log('Emmiting Module componentPath', componentId, componentPath);
-                try {
-                    const clientModuleSource = (0, build_1.generateClientComponentSource)(componentPath);
-                    const clientModuleJs = yield (0, build_1.buildClientModule)(clientModuleSource, handoff);
-                    this.emitFile({
-                        type: 'asset',
-                        fileName: `${componentId}.module.js`,
-                        source: clientModuleJs,
-                    });
-                }
-                catch (error) {
-                    logger_1.Logger.warn(`Failed to build client module for ${componentId}: ${error}`);
-                }
                 // Format final HTML and update component data
                 finalHtml = yield (0, html_1.formatHtml)(finalHtml);
                 componentData.format = 'react';

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

@@ -1,5 +1,4 @@
 import esbuild from 'esbuild';
-import Handoff from '../../index';
 /**
  * Default esbuild configuration for SSR builds
  */
@@ -26,20 +25,3 @@ export declare function createReactResolvePlugin(workingPath: string, handoffMod
     name: string;
     setup(build: any): void;
 };
-/**
- * Generates the entry source for a standalone client-side React component module.
- * The resulting module exports `render(container, props)` and `update(props)`
- * so the Playground can dynamically load and re-render it in an iframe.
- */
-export declare function generateClientComponentSource(componentPath: string): string;
-/**
- * Generates the entry source for a standalone CSF component module.
- * Replicates the story rendering logic (meta.render / story.render / meta.component)
- * so the Playground can render CSF components client-side.
- */
-export declare function generateCsfClientComponentSource(componentPath: string, storyKey: string): string;
-/**
- * Builds a self-contained browser ESM module from the given source code.
- * React and ReactDOM are bundled into the output so the module works standalone.
- */
-export declare function buildClientModule(sourceCode: string, handoff: Handoff): Promise<string>;

package/dist/transformers/utils/build.js

@@ -1,13 +1,4 @@
 "use strict";
-var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
-    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
-    return new (P || (P = Promise))(function (resolve, reject) {
-        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
-        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
-        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
-        step((generator = generator.apply(thisArg, _arguments || [])).next());
-    });
-};
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
@@ -15,12 +6,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.DEFAULT_CLIENT_BUILD_CONFIG = exports.DEFAULT_SSR_BUILD_CONFIG = void 0;
 exports.resolveModule = resolveModule;
 exports.createReactResolvePlugin = createReactResolvePlugin;
-exports.generateClientComponentSource = generateClientComponentSource;
-exports.generateCsfClientComponentSource = generateCsfClientComponentSource;
-exports.buildClientModule = buildClientModule;
-const esbuild_1 = __importDefault(require("esbuild"));
 const path_1 = __importDefault(require("path"));
-const logger_1 = require("../../utils/logger");
 /**
  * Default esbuild configuration for SSR builds
  */
@@ -88,97 +74,3 @@ function createReactResolvePlugin(workingPath, handoffModulePath) {
         },
     };
 }
-function toForwardSlash(p) {
-    return p.replace(/\\/g, '/');
-}
-/**
- * Generates the entry source for a standalone client-side React component module.
- * The resulting module exports `render(container, props)` and `update(props)`
- * so the Playground can dynamically load and re-render it in an iframe.
- */
-function generateClientComponentSource(componentPath) {
-    return `
-    import React from 'react';
-    import { createRoot } from 'react-dom/client';
-    import Component from '${toForwardSlash(componentPath)}';
-
-    let root = null;
-
-    export function render(container, props) {
-      root = createRoot(container);
-      root.render(React.createElement(Component, props));
-      return root;
-    }
-
-    export function update(props) {
-      if (root) {
-        root.render(React.createElement(Component, props));
-      }
-    }
-  `;
-}
-/**
- * Generates the entry source for a standalone CSF component module.
- * Replicates the story rendering logic (meta.render / story.render / meta.component)
- * so the Playground can render CSF components client-side.
- */
-function generateCsfClientComponentSource(componentPath, storyKey) {
-    return `
-    import React from 'react';
-    import { createRoot } from 'react-dom/client';
-    import * as stories from '${toForwardSlash(componentPath)}';
-
-    const meta = stories.default || {};
-    const story = stories['${storyKey}'];
-
-    let root = null;
-
-    function renderElement(props) {
-      const storyRender = typeof story === 'function' ? story : (story && story.render);
-      const renderFn = storyRender || meta.render;
-      if (renderFn) {
-        const result = renderFn(props);
-        return React.isValidElement(result) ? result : React.createElement(meta.component, props);
-      }
-      if (meta.component) {
-        return React.createElement(meta.component, props);
-      }
-      return React.createElement('pre', null, JSON.stringify(props, null, 2));
-    }
-
-    export function render(container, props) {
-      root = createRoot(container);
-      root.render(renderElement(props));
-      return root;
-    }
-
-    export function update(props) {
-      if (root) {
-        root.render(renderElement(props));
-      }
-    }
-  `;
-}
-/**
- * Builds a self-contained browser ESM module from the given source code.
- * React and ReactDOM are bundled into the output so the module works standalone.
- */
-function buildClientModule(sourceCode, handoff) {
-    return __awaiter(this, void 0, void 0, function* () {
-        var _a, _b;
-        const config = Object.assign(Object.assign({}, exports.DEFAULT_CLIENT_BUILD_CONFIG), { logLevel: 'silent', stdin: {
-                contents: sourceCode,
-                resolveDir: process.cwd(),
-                loader: 'tsx',
-            }, plugins: [createReactResolvePlugin(handoff.workingPath, handoff.modulePath)] });
-        const finalConfig = ((_b = (_a = handoff.config) === null || _a === void 0 ? void 0 : _a.hooks) === null || _b === void 0 ? void 0 : _b.clientBuildConfig)
-            ? handoff.config.hooks.clientBuildConfig(config)
-            : config;
-        const result = yield esbuild_1.default.build(finalConfig);
-        if (result.warnings.length > 0) {
-            const messages = yield esbuild_1.default.formatMessages(result.warnings, { kind: 'warning', color: true });
-            messages.forEach((msg) => logger_1.Logger.warn(msg));
-        }
-        return result.outputFiles[0].text;
-    });
-}

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

@@ -3,7 +3,6 @@ import { Types as HandoffTypes } from 'handoff-core';
 import { InlineConfig } from 'vite';
 import { SlotMetadata } from '../transformers/preview/component';
 import { ComponentListObject, TransformComponentTokensResult } from '../transformers/preview/types';
-import { PageListObject } from '../transformers/preview/page/types';
 import { ValidationResult } from './preview';
 export interface ImageStyle {
     name: string;
@@ -114,11 +113,6 @@ export interface Config {
          * @example ["components/button", "components/input"]
          */
         components?: string[];
-        /**
-         * Array of page paths to be included in the build
-         * @example ["pages/homepage", "pages/about"]
-         */
-        pages?: string[];
     };
     /**
      * Configuration for asset zip file download links
@@ -136,16 +130,6 @@ export interface Config {
          */
         logos?: string;
     };
-    /**
-     * Platform project ID (UUID). Set by `platform:init` to link this
-     * local project with a remote handoff-service project.
-     */
-    platformProjectId?: string;
-    /**
-     * Platform base URL (e.g. "http://localhost:3000" or "https://handoff.example.com").
-     * Set by `platform:init` so subsequent sync commands know where to connect.
-     */
-    platformUrl?: string;
     /**
      * Configuration hooks for extending functionality
      */
@@ -277,9 +261,6 @@ export interface RuntimeConfig {
         components: {
             [id: string]: ComponentListObject;
         };
-        pages: {
-            [id: string]: PageListObject;
-        };
     };
     options: {
         [key: string]: RuntimeConfigComponentOptions;

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